@misoto22/folio 0.0.0 → 0.17.0

package/dist/agent/Workbench.md

@@ -0,0 +1,142 @@
+# Workbench
+
+Section rhythm, hero, cards, entries, timeline, mosaic and scroll reveal for the Workbench preset.
+
+- Kind: pattern
+- Group: Website
+- Import: `import { WorkbenchSection } from '@misoto22/folio/website'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/workbench/
+
+## When to reach for it
+
+Lay a portfolio page on one 12-column grid with two-tone headings, and apply WORKBENCH_THEME on the root.
+
+## Best practices
+
+### Do
+
+- Wrap each section in WorkbenchSection so headings and content share the same columns.
+
+### Don’t
+
+- Do not hide content until JavaScript runs; Reveal only hides elements that start below the fold after hydration.
+
+## WorkbenchSection
+
+The Workbench section: a hairline, a two-tone heading in the first four columns, and the content on an eight-column subgrid beside it. Every section on a Workbench page uses this one rhythm, which is what keeps them aligned.
+
+### Props
+
+- `title` (required) — `ReactNode`. The heading's first, ink-coloured clause.
+- `lead` — `ReactNode`. The muted continuation that follows the title in the same line.
+- `action` — `ReactNode`. One accent link under the heading, such as "All projects →".
+- `level` — `2 | 3` default `2`. Heading level; sections on a page are h2.
+- `id` — `string`.
+- `children` (required) — `ReactNode`.
+
+## Chronology
+
+Roles and studies as bars on one year axis, one lane each. Roles are filled, studies outlined, and a current role is ink with an accent end. The bars are a list underneath, so a screen reader hears titles and dates rather than geometry.
+
+### Props
+
+- `label` (required) — `string`. Accessible name of the chart.
+- `from` (required) — `number`. First and last year on the axis, inclusive.
+- `to` (required) — `number`.
+- `items` (required) — `ChronologyItem[]`.
+- `currentLabel` — `ReactNode`. Text marking a current item, such as "Now".
+
+## ContactRow
+
+An address and one action on a single line of the content subgrid.
+
+### Props
+
+- `address` (required) — `ReactNode`. The address, set large — usually a `mailto:` link.
+- `action` — `ReactNode`. One button beside it.
+
+## PhotoMosaic
+
+One large photograph beside a 2×2 of smaller ones, all on the content subgrid.
+
+### Props
+
+- `children` (required) — `ReactNode[]`. Exactly the photographs to show: the first is the large one, the next four fill a 2×2 beside it.
+- `caption` — `ReactNode`. Caption under the large photograph.
+
+## Reveal
+
+Fades and lifts its child the first time it scrolls into view. The server renders the child visible. Only after hydration, and only for an element that starts below the fold, is it hidden and then revealed — so a page without JavaScript, a crawler and anything already on screen never see an empty frame. Reduced motion skips the whole thing, and the duration is the motion axis's own, so `data-motion="still"` makes it instant.
+
+### Props
+
+- `children` (required) — `ReactElement`. One element; it keeps its own tag and receives the reveal state.
+
+## ToolStrip
+
+A row of equal tiles, one monochrome tool mark each, under a centred caption.
+
+### Props
+
+- `label` (required) — `ReactNode`.
+- `items` (required) — `ToolStripItem[]`.
+
+## WorkbenchCard
+
+An image-led record. The title's link is stretched over the card, so the card is one target without nesting interactive elements.
+
+### Props
+
+- `cover` (required) — `ReactNode`. A cover image, or a `WorkbenchTile` when there is no picture.
+- `title` (required) — `ReactNode`. The title, usually a link; the whole card becomes its hit area.
+- `description` — `ReactNode`.
+- `meta` — `ReactNode`.
+
+## WorkbenchCardGrid
+
+Two cards per row on the content subgrid, one on a phone.
+
+### Props
+
+- `children` (required) — `ReactNode`.
+
+## WorkbenchTile
+
+A typographic stand-in cover: ink ground, a fine grid, one word.
+
+### Props
+
+- `label` (required) — `ReactNode`. Large word set on the tile, such as a product name.
+
+## WorkbenchEntries
+
+A featured entry set as a tile, with the next few entries stacked beside it.
+
+### Props
+
+- `featured` — `WorkbenchEntry`. Shown as a typographic notebook tile; the rest list beside it.
+- `entries` (required) — `WorkbenchEntry[]`.
+
+## WorkbenchFigure
+
+A photograph shown as a photograph: its own proportion, an 8px corner, and a caption line beneath — never a backdrop for something else.
+
+### Props
+
+- `children` (required) — `ReactElement`. The image element (or a host image component); it fills the frame.
+- `title` — `ReactNode`. Caption start: the photograph's title.
+- `meta` — `ReactNode`. Caption end: place and year, right-aligned.
+- `ratio` — `'wide' | 'landscape' | 'portrait' | 'panorama'` default `'landscape'`. Frame proportion.
+
+## WorkbenchHero
+
+The Workbench opening: a two-tone statement, its actions, a few counts and one photograph.
+
+### Props
+
+- `statement` (required) — `ReactNode`. The ink clause of the statement; it is the page's h1.
+- `lead` — `ReactNode`. The muted continuation of the statement.
+- `actions` — `ReactNode`. Up to two buttons or links, primary first.
+- `stats` — `WorkbenchStat[]` default `[]`. Small counts beside the statement, such as projects and posts.
+- `figure` — `ReactNode`. One captioned photograph under the statement — a `WorkbenchFigure`.

package/dist/agent/WorkflowFigure.md

@@ -0,0 +1,51 @@
+# WorkflowFigure
+
+A process in lanes and phases, with the main path drawn heavier than its branches.
+
+- Kind: component
+- Group: Diagrams
+- Import: `import { WorkflowFigure } from '@misoto22/folio/diagrams'`
+- Version: 0.17.0
+- Docs: https://ui.misoto22.com/components/workflow-figure/
+- Related: lifecycle-figure, sequence-figure, steps
+
+## When to reach for it
+
+A runbook, an approval chain, a CI pipeline — anything with an owner per step. mainPath is what turns fourteen boxes into a diagram with a subject.
+
+## Anatomy
+
+- **Figure shell** (required) — The same frame every figure sits in. What a process hands it is a key of LINE variants rather than of node kinds — Call, Primary path, Crosses a trust boundary, Asynchronous — because a runbook is read for its arrows and not for its boxes.
+- **Lane** (required) — A 92-unit band per lane with its name set in the 118-unit gutter to its left. The band spans only what the lane actually holds, and a lane marked exception is washed rather than ruled — the one wash in the package’s diagrams, because nothing routes across it.
+- **Column** (required) — What col indexes: a 168-unit column with a 58-unit gutter, the same across every lane. A node sits centred in its lane’s depth, moved off that centre line only by yOffset.
+- **Phase header** — A mono caption at the x of its fromCol, over a rule drawn across the columns from fromCol to toCol — so a phase’s extent is something a reader can see rather than a field only its author knows. variant dashes that rule for security and thickens it for emphasis. A phase is an axis label, so it is set like one rather than framed.
+- **Group frame** — A labelled rule around a run of columns inside ONE lane — a planning loop, an evidence path — dashed when its variant is security.
+- **Main path** — mainPath, drawn as weight rather than as a mark of its own: every edge between two consecutive ids on it goes heavier whatever its own variant says.
+
+## Best practices
+
+### Do
+
+- Give every node a lane that spec.lanes declares. An unknown lane id still resolves to the first lane — there is nowhere else to put the box — so a step written for the exception band is drawn in the right column, at the right size, in the wrong row, and development prints DIAGRAM_LANE_UNKNOWN naming the node.
+- Write mainPath as the path in order. The heavier weight is applied to CONSECUTIVE pairs, so [intake, review, ship] emphasises intake→review and review→ship and nothing else; an id whose neighbour on the list is not the far end of a real edge changes nothing at all.
+- Say what an edge MEANS with role and let the drawing follow it. async and error take the quiet dashed line, return takes an open arrowhead, and main and branch add no stroke of their own because mainPath already draws that distinction as weight. An explicit variant overrides all of it, which is what it is for.
+
+### Don’t
+
+- Phases partition the columns; they do not stack. Each is drawn as a rule across its own span, so two phases claiming the same columns put two rules on one line and one caption over the other — and a reader cannot tell that from one phase drawn twice.
+- An empty lane is not a spacer. The band is sized from what the lane holds, so a lane with no nodes collapses to about one column beside the gutter with its name still set — and an exception lane in that state washes a strip of ground next to the figure rather than under the failure path.
+
+## Accessibility
+
+- Same contract as every figure: a named picture, with its nodes and relationships published as text beside it.
+- The exception lane is the one washed band in the system’s diagrams, and it is still labelled — the wash is not carrying the meaning on its own.
+
+## WorkflowFigure
+
+A process: who does what, in what order, and where it can go wrong. Three structures stacked on one grid, and they are three because they answer three different questions a reader brings to a runbook. **Lanes** are rows and answer WHO. A lane marked `exception` is the one band that gets a wash rather than a rule, and it earns the exception to the frames-are-rules law because nothing routes across it — it IS the ground for the failure path, not a frame drawn over the happy one. **Phases** are columns across every lane and answer WHEN. Printed as captions on one header rule, because a phase is an axis label. **Groups** are frames inside a single lane and answer WHAT BELONGS TOGETHER — a planning loop, an evidence path. THE MAIN PATH IS HEAVIER, and that is the whole hierarchy. `mainPath` lists the node ids a reader should be able to follow without thinking. Every edge between two consecutive ids on it is drawn at the emphasis weight whatever its own variant says, which is the one thing that turns fourteen boxes and nineteen arrows into a diagram with a subject. An `error` role goes the other way — dashed and soft — so the exception path recedes without disappearing, and so does `async`. `branch` adds no stroke of its own: a branch is an edge the main path does not list, and that is already the difference on the page.
+
+### Props
+
+- `spec` (required) — `WorkflowSpec`.
+
+Also accepts: `FigureChrome`.