@nadicodeai/ui 6.6.2 → 7.1.0

package/docs/threshold.md

@@ -1,221 +0,0 @@
-# The threshold primitives
-
-`@nadicodeai/ui/threshold` holds the four primitives a threshold is drawn from. A
-threshold is the moment before the product is usable: a first run, a sign-in, a
-repair. The Nadia desktop app draws its room, presence, status orb and typed line
-from here, so the brand logic has one home.
-
-The entry ships no screen and no state machine. Which view is on, what the
-words are, and when a threshold ends belong to the consuming app.
-
-```tsx
-import { NadiaPresence, Orb, ThresholdRoom, TypedLine } from "@nadicodeai/ui/threshold";
-import "@nadicodeai/ui/threshold.css";
-```
-
-## What each part is for
-
-| Part | Its one job | Never |
-| --- | --- | --- |
-| `ThresholdRoom` | the place: a verde field on true black | inside the working app |
-| `NadiaPresence` | the host: her arrival is the progress | a loader, a ring, a bar |
-| `Orb` | system work underway, through the shared activity renderer | reporting a failed operation or waiting on a person as ongoing work |
-| `TypedLine` | what Nadia is saying while you wait | a control or state machine |
-
-The logo is not on this list. It belongs to window chrome, the tray and the
-About row, never to a threshold.
-
-## The stylesheet
-
-`@nadicodeai/ui/threshold.css` is a separate import rather than a part of
-`globals.css`, because the surface that needs it most does not load Tailwind:
-the Nadia desktop shell takes this file and the design-system token layer and
-nothing else from this package. A Tailwind consumer imports it beside
-`@nadicodeai/ui/globals.css`.
-
-Both the stylesheet and the room need the design-system tokens above them, from
-`@nadicodeai/ui/globals.css` or `@nadicodeai/design-system/css`. Without that
-cascade there is no palette, and the room paints its still field rather than
-guessing a colour.
-
-## `ThresholdRoom`
-
-```tsx
-<div className="relative isolate overflow-hidden">
-  <ThresholdRoom energy={arriving ? 1 : 0} dimmed={repairing} ready={connected} />
-  {/* the presence and the words, above it */}
-</div>
-```
-
-| Prop | Type | Default | Meaning |
-| --- | --- | --- | --- |
-| `dimmed` | `boolean` | `false` | a repair or an error quiets the room to 22 percent |
-| `energy` | `number` | `0` | how much of the room's pace runs, 0 to 1 |
-| `ready` | `boolean` | `false` | success: the field takes verde vivo |
-| `className` | `string` | — | added to the root |
-
-The room paints absolutely inside its own relative, isolated parent and never
-against the viewport, so a bounded surface can hold one without covering the
-page. It is `aria-hidden`, takes no pointer events, and carries no words.
-
-**The recipe.** Paper Shaders 0.0.78 `meshGradientFragmentShader`, its published
-Ink preset adapted to two colours and slowed: `u_colors` are
-`--nc-identity-verde` and `--nc-identity-ink`, `u_colorsCount` 2, `u_distortion`
-1, `u_swirl` 0.2, `u_rotation` 90, `u_grainMixer` and `u_grainOverlay` 0, fit
-contain, scale 1. Mount speed is 0.22 at energy 1, starting frame 12000, minimum
-pixel ratio 1, maximum pixel count 1,024,000, canvas opacity 0.65. The room is
-masked with `radial-gradient(ellipse 65% 58% at 50% 35%, black 10%, transparent
-95%)`. The two colours are shader uniforms, never CSS.
-
-`energy` is a scalar so a screen can decide. The captured recipe is energy 1;
-Nadia's first run holds it there while she is still arriving and drops it to 0
-when she has, which stills the field. Sign-in, success and every repair state
-pass 0.
-
-**One canvas per window.** While `NadiaPresence` is painting her arrival with
-water, the room mounts nothing and shows this same still field; the moment the
-water leaves, at reveal 1 or when it cannot paint, the room's canvas mounts.
-The budget lives in the package, so a surface that composes both, as first run
-does, keeps the register's one shader canvas without doing anything.
-
-**No GPU, no tokens, or a lost context.** The room keeps its still field: a
-token-built radial gradient that needs no WebGL. It carries `data-surface`,
-`"shader"` while the canvas paints and `"still"` otherwise, and a mount that
-fails leaves no dead canvas covering the fallback. A `webglcontextlost` event
-returns it to the still field rather than to a black rectangle.
-
-**Reduced motion.** Speed 0: the shader paints frame 12000 once and stops. The
-room still has its colour and its shape; it just holds one frame.
-
-## `NadiaPresence`
-
-```tsx
-<NadiaPresence label={t("install.progress")} reveal={fraction} src={portrait} state="arriving" />
-```
-
-| Prop | Type | Meaning |
-| --- | --- | --- |
-| `label` | `string` | the accessible name of the arrival |
-| `reveal` | `number` | 0 behind the field, 1 standing clear |
-| `src` | `string` | the portrait master's URL |
-| `state` | `"arriving" \| "present" \| "ready" \| "error"` | which threshold she is in |
-
-`src` is a prop rather than an import because this package imports no binary
-asset of its own; the consuming surface resolves
-`@nadicodeai/design-system/assets/nadia-solid-surface` with its own bundler and
-passes the URL. Keeping it out of the library is what lets a Node or a
-bundler-free consumer load the module at all.
-
-**The arrival.** Opacity is `0.025 + 0.975 × reveal^1.25`, exported as
-`arrivalOpacity` so a screen can read the same curve. At the start she is a
-trace, which gives the arrival somewhere to go. Her lower edge dissolves into
-the room with `linear-gradient(black 55%, transparent 98%)` instead of ending on
-a rectangle. The `error` state multiplies her by 0.62.
-
-**The water.** While `state` is `arriving`, `reveal` is below 1 and motion is
-allowed, the portrait is painted by Paper's `waterFragmentShader` at a
-restrained intensity: `caustic`, `edges` and `waves` are `0.35`, `0.4` and `0.3`
-scaled by how much of the arrival is left, with `layering` 0.4 and `highlights`
-0.12, `colorBack` fully transparent and `colorHighlight` on
-`--nc-identity-verde`. Every amplitude reaches zero as she arrives, so her
-geometry holds and the water is gone by the time she stands clear. At reveal 1,
-and in every other state, this is the plain portrait.
-
-While the water is wanted it is the window's one shader canvas: the presence
-holds the canvas budget from the moment it asks for the water until the water
-is torn down, and the room keeps its still field for exactly that long.
-
-The water canvas is masked to her own silhouette. Water adds its highlight term
-to the whole frame rather than only to the sampled image, so an unmasked canvas
-paints a faintly lit rectangle over the room; the mask matches the shader's own
-contain fit and centred origin.
-
-**Reduced motion, no GPU, or an image that will not decode.** The plain
-portrait, at the same reveal. The figure carries `data-surface`, `"water"` or
-`"portrait"`.
-
-**Success.** `state="ready"` runs one 360 ms verde vivo beat over her silhouette
-on `--nc-ease-out-strong`, opacity 0 to 0.22 at 35 percent and back to 0, once.
-Verde vivo is Nadia's presence accent and this is the only place a threshold
-spends it, which is why the buttons beside it stay neutral. Reduced motion
-suppresses the beat.
-
-**Assistive technology.** A hidden `progressbar` carries `label` and the floored
-percentage, so it reaches 100 only when the arrival is actually finished. The
-portrait itself is decorative; the words are the typed line's.
-
-## `Orb`
-
-```tsx
-<Orb label={t("install.working")} state="working" />
-```
-
-| Prop | Type | Default | Meaning |
-| --- | --- | --- | --- |
-| `label` | `string` | — | what the orb means, in the Customer's language |
-| `size` | `88 \| 64 \| 20` | `88` | CSS pixels: threshold, region, or inline operation; see `activity.md` |
-| `state` | `"working" \| "connecting" \| "absent"` | — | see below |
-
-The threshold adapter preserves its public states: `working` selects the
-shared `processing` activity, `connecting` selects `connecting`, and `absent`
-renders nothing. The threshold defaults to fixed dark ink; `theme="auto"`
-inherits the surrounding product's ink and `theme="light"` fixes light-surface
-ink. There is one renderer, `ActivityOrb`, rather than a second threshold orb.
-
-[System activity](activity.md) owns the motion recipes, colour treatment,
-optical sizes, reduced-motion behaviour and connection-versus-person-waiting
-rule. Applications retain their operation state machines and copy.
-
-## `TypedLine`
-
-```tsx
-<TypedLine text={t("install.step.1")} />
-```
-
-| Prop | Type | Default |
-| --- | --- | --- |
-| `cadenceMs` | `number` | `44` |
-| `text` | `string` | — |
-| `className` | `string` | — |
-
-The line types itself at 44 ms per character, the cadence the rendered
-comparisons selected for a first-run pause. Three things it does that a naive
-typewriter does not:
-
-- the count comes from elapsed time, not from how many callbacks arrived, so a
-  software renderer or a busy main thread cannot stretch a one second sentence
-  into five;
-- a hidden copy of the whole sentence reserves its width, so the orb beside it
-  does not travel sideways with each character;
-- the live region receives the complete sentence at once, so a screen reader is
-  never read one letter at a time.
-
-A new `text` retypes from a cleared line. The caret is steady while typing and
-hidden afterwards.
-
-**Reduced motion.** The whole line at once, and no caret.
-
-## Tokens, and the one fixed presentation
-
-Everything visual comes from design-system tokens. A threshold is a fixed dark
-surface: it is true black in every theme, so the text ladder reads
-`--nc-dark-ink`, `--nc-dark-body` and `--nc-dark-muted` directly instead of
-branching on the app's mode. That is the fixed-presentation escape
-[`contract.md`](contract.md) names, taken once and coherently for the whole
-surface.
-
-The room's two colours are the exception that proves it: they are shader
-uniforms read off `--nc-identity-verde` and `--nc-identity-ink` at mount, not
-CSS values.
-
-## Motion budget
-
-The foundation's: `--nc-duration-open` for a room fading in or out,
-`--nc-duration-confirm` for the presence, `--nc-ease-emphasized` and
-`--nc-ease-out-strong`. The success beat is the one
-duration written here rather than taken from a token, 360 ms, because it is an
-envelope rather than a state change.
-
-Under `prefers-reduced-motion: reduce` the room holds one frame, the water is
-not mounted, the presence jumps to its value, the beat does not run, the orb
-draws once and the line appears whole.