lineal:0.2.0

packages/preview/lineal/0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Elliott Phillips
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/preview/lineal/0.2.0/README.md

@@ -0,0 +1,146 @@
+# Lineal
+
+Clean Typst presentations with reusable content components.
+
+Lineal provides a slide theme, composable layouts and components for talks,
+teaching material and project reviews. The components also work in ordinary
+Typst documents. Content stays editable and selectable in the exported PDF.
+
+![A team update composed with Lineal components](https://raw.githubusercontent.com/ellsphillips/lineal/941f266c40b5b24ba881fded1e6a52d6eafec8de/assets/img/components.png)
+
+## Quick start
+
+Requires **Typst 0.13.1 or newer**. Version 0.2.0 is a release candidate until
+the registry submission is published. Use the source checkout or local package
+instructions below to try it now.
+
+Create `talk.typ` with the public package API:
+
+```typst
+#import "@preview/lineal:0.2.0": lineal-theme, config-info, title-slide, layouts, metric, callout
+
+#show: lineal-theme.with(
+  aspect-ratio: "16-9",
+  config-info(title: [Project review], author: [Your name]),
+)
+
+#title-slide()
+
+= Delivery
+== Progress this quarter
+
+#layouts.columns(
+  metric(12, label: [Teams onboarded]),
+  metric(4, label: [Workshops delivered]),
+)
+#v(1em)
+#callout(title: [Next step])[Share the workshop materials with each team.]
+```
+
+Compile with `typst compile --root . talk.typ`. Level-one headings create
+section slides with an outline. Level-two headings create content slides.
+Deeper headings stay within a slide. Set `footer-progress: false` to hide the
+progress bar or customise the running headers and footers.
+
+## Source checkout and local packages
+
+**Version 0.2.0 is a release candidate in this repository.** The published
+`0.1.0` package lacks the `lineal-theme` export. Updating a local checkout does
+not repair that older registry package.
+
+Clone the repository to compile the current gallery immediately:
+
+```sh
+git clone https://github.com/ellsphillips/lineal.git
+cd lineal
+typst compile --root . demo/main.typ demo/main.pdf
+```
+
+To use the quick-start example inside this checkout, change its import path to
+`"lib.typ"`. For a reusable local package, run:
+
+```sh
+python3 scripts/package --install-local
+```
+
+Then use the same API from any project:
+
+```typst
+#import "@local/lineal:0.2.0": lineal-theme, config-info, title-slide
+#show: lineal-theme.with(config-info(title: [My presentation]))
+#title-slide()
+== First slide
+Your content.
+```
+
+Local installation never replaces a published package or modifies the registry
+cache. The [release guide](docs/development.md) explains packaging and checks.
+
+## Components
+
+Import individual functions from `lib.typ` or the package entrypoint. Components
+inherit the surrounding font and accept local colours and spacing. They do not
+require the slide theme, JavaScript or network requests while rendering.
+
+| Component | Use |
+| --- | --- |
+| `code-block(source, filename: ...)` | Syntax highlighting, file icons, numbered lines, ranges, captions and light/dark styles. |
+| `file-icon(filename)` and `file-label(filename)` | SVG file marks and path labels, including a blue Svelte mark for `.svelte.ts`. |
+| `callout(title: ..., tone: ...)[body]` | Notes with an optional heading and a semantic accent. |
+| `metric(value, label: ..., detail: ..., change: ...)` | A prominent value with explicit context. |
+| `steps(items, direction: ...)` | Numbered processes in a vertical or horizontal layout. |
+| `data-table(headers, rows)` | Styled tables with repeating headers, alignment and highlighted rows. |
+| `comparison(before, after, labels: ...)` | Two labelled content areas with configurable proportions. |
+| `quote(author: ..., source: ...)[body]` | Quotations with optional rich attribution. |
+| `repository(name: ..., languages: ...)` | A repository link and a language bar with normalised percentages. |
+| `lineal-outline()` and `lineal-toc()` | Contextual section navigation and a complete, flowing table of contents. |
+| `lineal-progress-bar(variant: ...)` | Logical slide progress with correct section, overlay and handout counts. |
+
+Detailed signatures and working examples:
+
+- [Code blocks and file labels](docs/code-block.md)
+- [Callouts, metrics, steps, tables and comparisons](docs/components.md)
+- [Layouts, quotes, repositories and theme configuration](docs/layouts.md)
+- [Outlines and tables of contents](docs/navigation.md)
+- [Progress calculations and counter semantics](docs/progress.md)
+- [Heading hierarchy and overlay identity](docs/navigation-model.md)
+- [Complete component gallery](https://github.com/ellsphillips/lineal/blob/941f266c40b5b24ba881fded1e6a52d6eafec8de/demo/main.typ)
+
+## Composition
+
+Use the `layouts` namespace for common arrangements:
+
+```typst
+#layouts.columns(widths: (2fr, 1fr), gutter: 1em,
+  layouts.panel[Main content],
+  layouts.panel[Supporting content],
+)
+```
+
+`layouts.columns` accepts any number of bodies. `layouts.panel` sizes naturally
+to its content. `layouts.frame(height: 180pt)[body]` checks vertical overflow
+before drawing a fixed frame. The earlier `page-center`, `two-boxes`, `contained`,
+`four-columns` and `matrix` layouts remain available.
+
+Native Typst `grid`, `stack`, `table`, figures and links work alongside every
+component. Use `config-colors` for the slide frame and named colour options on
+components for local styling. See the [layout guide](docs/layouts.md).
+
+## Development
+
+```sh
+./scripts/check
+python3 scripts/package /tmp/lineal-package
+```
+
+The checks compile real examples and package imports, exercise expected errors
+and build the gallery. CI runs against Typst 0.13.1 and 0.14.2. Development
+scripts require Python 3.11 or newer; consuming Lineal requires only Typst.
+See [development and release instructions](docs/development.md).
+
+## Licence
+
+Lineal is MIT licensed. Bundled SVG assets retain their own MIT, ISC or CC0
+notices under `src/static/icons/`. Lineal builds on
+[Touying](https://github.com/touying-typ/touying) and
+[Typst](https://github.com/typst/typst).

packages/preview/lineal/0.2.0/docs/code-block.md

@@ -0,0 +1,136 @@
+# Code blocks and file labels
+
+`code-block` renders selectable source text with a filename header, syntax
+highlighting, line numbers and optional emphasis. It works inside a Lineal slide
+or an ordinary Typst document. Existing calls with a positional source string and
+`filename`, `language` or `theme` options continue to work.
+
+```typst
+#import "@preview/lineal:0.2.0": code-block
+
+#code-block(
+  read("counter.svelte"),
+  filename: "components/counter.svelte",
+  start-line: 20,
+  emphasize: (22, (25, 27)),
+  caption: [The input and derived label share the same state.],
+)
+```
+
+## Common settings
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `filename` | `"app.py"` | Display the path and infer the syntax language. |
+| `language` | `auto` | Override inference with a Typst language tag or familiar alias such as `"typescript"`. |
+| `style` | `"dark"` | Use `"dark"`, `"light"`, or a complete custom palette. |
+| `theme` | `auto` | Select the style's bundled syntax theme, disable colouring with `none`, or supply a tmTheme file. |
+| `size`, `font` | `12pt`, `"DejaVu Sans Mono"` | Source typography. The default code font ships with Typst. |
+| `body-font` | `none` | Header and caption font; `none` inherits the document font. |
+| `width` | `100%` | An absolute or container-relative width, including `100% - 12pt`. |
+| `height` | `none` | Fix the panel height to align neighbouring examples. |
+| `max-height` | `none` | Limit the combined height of the panel and caption. |
+| `show-header` | `true` | Hide filename chrome for compact comparison rows. Syntax inference still uses `filename`. |
+| `line-numbers` | `true` | Show one number per original logical source line. |
+| `start-line` | `1` | Set the first displayed source number. |
+| `emphasize` | `()` | Highlight displayed line numbers or inclusive `(first, last)` ranges. |
+| `wrap` | `true` | Wrap at natural text breakpoints while retaining the original line number. |
+| `caption` | `none` | Supporting content below the panel. |
+
+Additional controls are `padding: 12pt`, `line-gap: 0pt`, `radius: 7pt`,
+`header-size: 10.5pt`, `caption-size: 11pt`, `caption-fill: auto` and
+`tab-size: 2`. Caption colour inherits the surrounding text unless overridden.
+
+The component measures content before applying a fixed height. Source that does
+not fit raises an actionable error; it is never silently clipped or reduced to a
+smaller font. An unbreakable token wider than the source column fails even with
+wrapping enabled. Captions participate in `max-height` checks.
+
+Source strings retain indentation, interior blank lines and spaces. CRLF becomes
+LF, and only initial or final newline characters are trimmed. Highlighting uses
+native Typst raw text, so source remains selectable in exported PDFs.
+
+## Compact comparisons
+
+Use the same explicit height in both columns. No manual source padding or blank
+lines are needed to align panel bottoms.
+
+```typst
+#grid(columns: (1fr, 1fr), gutter: 16pt,
+  code-block(
+    "const label = useMemo(() => `${count}`, [count]);",
+    filename: "counter.tsx", show-header: false, height: 90pt,
+  ),
+  code-block(
+    "const label = $derived(`${count}`);",
+    filename: "counter.svelte.ts", show-header: false, height: 90pt,
+  ),
+)
+```
+
+## Light and custom themes
+
+`style: "light"` selects a matching light syntax theme and surface palette.
+`theme: none` disables syntax colouring without removing the header or emphasis.
+
+For a custom syntax theme, pass bytes read in your document. This preserves the
+location of your asset when importing Lineal as a package:
+
+```typst
+#code-block(
+  read("example.ts"), filename: "example.ts",
+  theme: read("assets/my-theme.tmTheme", encoding: none),
+)
+```
+
+Theme paths remain accepted for compatibility with native `raw` options. Byte
+input avoids ambiguity over a relative path's base directory.
+
+A custom surface palette has seven semantic colour roles. With `theme: auto`, a
+custom palette renders source in its `ink` colour. Supply `theme` explicitly when
+you also want syntax colouring.
+
+```typst
+#let green = (
+  ground: rgb("#eaf2ee"), raised: rgb("#f7fbf9"),
+  ink: rgb("#173f34"), muted: rgb("#527365"),
+  wire: rgb("#b9d2c7"), accent: rgb("#006b4b"),
+  "accent-text": rgb("#00543b"),
+)
+#code-block("let ready = true;", filename: "state.ts", style: green)
+```
+
+## File icons and labels
+
+These helpers can be used in diagrams, headers, file lists and comparison tables.
+
+```typst
+#import "@preview/lineal:0.2.0": file-icon, file-label
+
+#file-icon("state.svelte.ts", size: 18pt)
+#file-label("src/routes/+layout.server.ts", size: 15pt)
+```
+
+`file-icon(filename, size: 14pt, tint: ...)` uses local SVG assets. `.svelte`
+uses orange, `.svelte.ts` uses TypeScript blue, `.tsx`/`.jsx` use the React mark,
+and `.ts` uses the TypeScript mark. Other files use a generic icon in the requested
+tint. `file-label` distinguishes the directory from the basename and accepts
+`size`, `icon-size`, `font`, `fill`, `muted` and `gap` options. Its font inherits
+the document unless specified.
+
+Svelte syntax includes markup, directives, runes, embedded TypeScript and CSS.
+Multiline strings, comments and template interpolation retain their scope across
+lines. The grammars provide lexical highlighting, not type checking. Other common
+languages use Typst's bundled syntax definitions.
+
+## Checks and assets
+
+Compile `tests/code-block.typ` to inspect named styles, custom colours, wrapping,
+multiline syntax, icons, captions, start numbers and headerless panels.
+`tests/code-block-errors.typ` exercises explicit failure conditions with
+`--input case=height`, `range`, `nowrap` and the other cases listed in that file.
+
+All themes and syntax definitions are bundled and require no network requests.
+The Lineal themes and grammars use this project's MIT licence. SVG asset origins,
+exact commits and their CC0 or ISC licences are recorded under
+`src/static/icons/code/`.