@mythicalos/ui-core 0.2.1 → 0.2.2

package/dist/index.d.ts

@@ -4,3 +4,6 @@ export { typedNameMatches, BULLET_ICON, type DialogBullet } from "./logic/dialog
 export { composeToastText, TOAST_SEP, type ToastStatus, type ToastSpec, type ToastBus, } from "./logic/toast.js";
 export { gaugeTone, gaugeGeom, type GaugeGeom } from "./logic/gauge.js";
 export { chipClass, statusLineClass, bannerClass, BANNER_ICON, type Tone, type ChipTone, type StatusTone, type BannerTone, } from "./logic/tone.js";
+export { saveBarNote, saveBarDirty, saveBarClass, SAVE_BAR_PARTS, SAVE_BAR_SEP, SAVE_BAR_DISCARD_LABEL, SAVE_BAR_SAVE_LABEL, type SaveBarNote, } from "./logic/save-bar.js";
+export { statTilesClass, statTileClass, STAT_TILE_PARTS, formatStatCompact, formatStatCount, formatStatUsd, formatStatPercent, STAT_TILE_EMPTY, STAT_TILE_MINUS, type StatTile, type StatTileTone, } from "./logic/stat-tiles.js";
+export { gitFlags, hasGitStatus, gitBranchLabel, gitChipClass, gitFlagClass, gitChipNote, GIT_CHIP_PARTS, GIT_BRANCH_GLYPH, GIT_BRANCH_UNKNOWN, GIT_DETACHED_LABEL, GIT_CLEAN_LABEL, GIT_LOADING_NOTE, GIT_UNAVAILABLE_NOTE, GIT_STALE_LABEL, GIT_STALE_TITLE, type GitStatus, type GitFlag, type GitFlagTone, type GitChipState, } from "./logic/git-chip.js";

package/dist/index.js

@@ -7,3 +7,7 @@ export { typedNameMatches, BULLET_ICON } from "./logic/dialog.js";
 export { composeToastText, TOAST_SEP, } from "./logic/toast.js";
 export { gaugeTone, gaugeGeom } from "./logic/gauge.js";
 export { chipClass, statusLineClass, bannerClass, BANNER_ICON, } from "./logic/tone.js";
+// ── small atoms graduated out of a single product: save-bar, stat-tiles, git-chip ──
+export { saveBarNote, saveBarDirty, saveBarClass, SAVE_BAR_PARTS, SAVE_BAR_SEP, SAVE_BAR_DISCARD_LABEL, SAVE_BAR_SAVE_LABEL, } from "./logic/save-bar.js";
+export { statTilesClass, statTileClass, STAT_TILE_PARTS, formatStatCompact, formatStatCount, formatStatUsd, formatStatPercent, STAT_TILE_EMPTY, STAT_TILE_MINUS, } from "./logic/stat-tiles.js";
+export { gitFlags, hasGitStatus, gitBranchLabel, gitChipClass, gitFlagClass, gitChipNote, GIT_CHIP_PARTS, GIT_BRANCH_GLYPH, GIT_BRANCH_UNKNOWN, GIT_DETACHED_LABEL, GIT_CLEAN_LABEL, GIT_LOADING_NOTE, GIT_UNAVAILABLE_NOTE, GIT_STALE_LABEL, GIT_STALE_TITLE, } from "./logic/git-chip.js";

package/dist/logic/git-chip.d.ts

@@ -0,0 +1,79 @@
+/** Flag tone. Per the design card: warn = behind / uncommitted, error = unpushed ("a real error
+ *  state"), ok = clean. */
+export type GitFlagTone = "warn" | "error" | "ok";
+export interface GitFlag {
+    label: string;
+    tone: GitFlagTone;
+}
+/** A reported git status. Every field is REQUIRED so a caller cannot half-report a tree and get a
+ *  confident render — but each is also runtime-guarded, because a JS consumer can still pass
+ *  `undefined`, and "not reported" must degrade to honest silence, never to a fabricated zero. */
+export interface GitStatus {
+    /** Branch name, or `null` for a detached HEAD. */
+    branch: string | null;
+    /** Commits behind upstream. `null` ⇒ there is NO upstream — the flag is omitted, not zeroed. */
+    behind: number | null;
+    /** Uncommitted working-tree changes. */
+    uncommitted: number;
+    /** Commits not pushed to upstream. `null` ⇒ there is NO upstream — the flag is omitted. */
+    unpushed: number | null;
+}
+/** The branch glyph the card prefixes the name with. */
+export declare const GIT_BRANCH_GLYPH = "\u2387";
+/** Shown in place of a branch name when there is no status to show at all. */
+export declare const GIT_BRANCH_UNKNOWN = "\u2014";
+/** A `null` branch is a real, nameable state — never a blank. */
+export declare const GIT_DETACHED_LABEL = "detached HEAD";
+/** The all-clear flag (token rule #7: the ✓ glyph rides along with the ok-soft color). */
+export declare const GIT_CLEAN_LABEL = "clean \u2713";
+/** Default copy while the first status read is in flight. */
+export declare const GIT_LOADING_NOTE = "Checking repository status\u2026";
+/** Default copy when no status and no reason were supplied — deliberately says nothing about the
+ *  tree's actual state. */
+export declare const GIT_UNAVAILABLE_NOTE = "Repository status is unavailable.";
+/** Marker for a RETAINED status shown while the live read is failing: what is on screen is the last
+ *  received status, not the current one. */
+export declare const GIT_STALE_LABEL = "\u00B7 stale";
+export declare const GIT_STALE_TITLE = "the last read failed \u2014 showing the last received status";
+/** True when a status object was actually supplied. A JS caller can hand `null` where the type says
+ *  `GitStatus | undefined` — `null` means "no status", so it must take the honest unavailable arm
+ *  rather than crash on a field read. Both bindings gate on this. */
+export declare function hasGitStatus(status: GitStatus | null | undefined): status is GitStatus;
+/** Branch label: the real name, or the honest "detached HEAD" for `null`. An unreported branch
+ *  (`undefined`, or any non-string) falls back to the neutral `—` rather than inventing a checkout
+ *  state. */
+export declare function gitBranchLabel(branch: string | null | undefined): string;
+/** Counter flags in design order (behind · uncommitted · unpushed), collapsing to a single
+ *  `clean ✓` when the tree is genuinely all-clear.
+ *
+ *  The clean claim is guarded: it is made ONLY when `uncommitted` was reported as 0 AND both
+ *  upstream counters were reported at all — `null` counts as reported (it is the explicit "no
+ *  upstream" answer), `undefined` does not. A status that never reported its counters therefore
+ *  yields NO flags rather than a green "clean ✓" the caller never earned. */
+export declare function gitFlags(status: GitStatus): GitFlag[];
+export interface GitChipState {
+    /** No status to show — the chip renders its note instead of flags. */
+    unavailable?: boolean;
+    /** The shown status is retained, not current. */
+    stale?: boolean;
+}
+/** Every class the chip renders, root and elements — the bindings import these rather than
+ *  spelling the strings themselves, so the two frameworks cannot drift apart on a rename. */
+export declare const GIT_CHIP_PARTS: {
+    readonly root: "my-gitchip";
+    readonly branch: "my-gitchip__branch";
+    readonly flags: "my-gitchip__flags";
+    readonly flag: "my-gitchip__flag";
+    readonly note: "my-gitchip__note";
+    readonly stale: "my-gitchip__stale";
+};
+/** Root class: base + the unavailable/stale modifiers. */
+export declare function gitChipClass(state?: GitChipState): string;
+/** Flag badge class: base + tone modifier (always present — the tone IS the flag's meaning). */
+export declare function gitFlagClass(tone: GitFlagTone): string;
+/** The unavailable arm's sentence: a caller-supplied reason wins; else the loading line while the
+ *  first read is in flight; else the neutral default. Never describes the tree. */
+export declare function gitChipNote(o?: {
+    unavailableNote?: string;
+    loading?: boolean;
+}): string;

package/dist/logic/git-chip.js

@@ -0,0 +1,118 @@
+// @mythicalos/ui-core — the git status chip's flag derivation, branch label, copy and class
+// derivation (ds/components-git-chip.html: a bordered inline mono chip — `⎇ <branch>` plus honest
+// counter flags; warn-soft for behind/uncommitted, error-soft for unpushed, ok-soft for a clean
+// tree — "never red unless something is actually wrong").
+//
+// Extracted from the reference implementation in the reference product's session detail pane. Two
+// things were product-shaped there and are lifted out:
+//   1. the `available:false` REASON VOCABULARY (`no_worktree`, `uid_isolation_unsupported`,
+//      `session_terminal`, `slugless`, …) and its copy table — those are one daemon's wire enum.
+//      The atom keeps the STATE and takes the human sentence as `unavailableNote`, so each product
+//      maps its own reason codes to copy and the atom still renders the honest arm.
+//   2. the session view-model envelope (`GitVm`) — replaced by the plain `GitStatus` below.
+//
+// What is DESIGN and therefore stays (the honesty contract — see gitFlags):
+//   - `branch: null` is a DETACHED HEAD, rendered as such, never blank,
+//   - `behind`/`unpushed` of `null` means NO UPSTREAM: that flag is OMITTED, never rendered "0
+//     behind" (a `0` would claim an upstream comparison that never happened),
+//   - an absent/unreported status is NEVER coerced into a zero-count "clean ✓" row — the chip
+//     renders its unavailable arm (or, for a partially reported status, simply no flags).
+/** The branch glyph the card prefixes the name with. */
+export const GIT_BRANCH_GLYPH = "⎇";
+/** Shown in place of a branch name when there is no status to show at all. */
+export const GIT_BRANCH_UNKNOWN = "—";
+/** A `null` branch is a real, nameable state — never a blank. */
+export const GIT_DETACHED_LABEL = "detached HEAD";
+/** The all-clear flag (token rule #7: the ✓ glyph rides along with the ok-soft color). */
+export const GIT_CLEAN_LABEL = "clean ✓";
+/** Default copy while the first status read is in flight. */
+export const GIT_LOADING_NOTE = "Checking repository status…";
+/** Default copy when no status and no reason were supplied — deliberately says nothing about the
+ *  tree's actual state. */
+export const GIT_UNAVAILABLE_NOTE = "Repository status is unavailable.";
+/** Marker for a RETAINED status shown while the live read is failing: what is on screen is the last
+ *  received status, not the current one. */
+export const GIT_STALE_LABEL = "· stale";
+export const GIT_STALE_TITLE = "the last read failed — showing the last received status";
+/** A real, non-negative INTEGER commit/file count. `null` (no upstream), `undefined` (not
+ *  reported), `NaN`, negatives and fractions are all "not a count" — a fractional value cannot be a
+ *  number of commits, so it is malformed data and must not be rendered as one ("1.5↓ behind"). */
+function isCount(n) {
+    return typeof n === "number" && Number.isInteger(n) && n >= 0;
+}
+/** True when a status object was actually supplied. A JS caller can hand `null` where the type says
+ *  `GitStatus | undefined` — `null` means "no status", so it must take the honest unavailable arm
+ *  rather than crash on a field read. Both bindings gate on this. */
+export function hasGitStatus(status) {
+    return typeof status === "object" && status !== null;
+}
+/** Branch label: the real name, or the honest "detached HEAD" for `null`. An unreported branch
+ *  (`undefined`, or any non-string) falls back to the neutral `—` rather than inventing a checkout
+ *  state. */
+export function gitBranchLabel(branch) {
+    if (branch === null)
+        return GIT_DETACHED_LABEL;
+    if (typeof branch !== "string")
+        return GIT_BRANCH_UNKNOWN;
+    // A git ref name cannot contain whitespace, so blank-or-whitespace is the same malformed input as
+    // `""` — it must not leave the branch slot visibly empty next to a confident status.
+    return branch.trim().length > 0 ? branch : GIT_DETACHED_LABEL;
+}
+/** Counter flags in design order (behind · uncommitted · unpushed), collapsing to a single
+ *  `clean ✓` when the tree is genuinely all-clear.
+ *
+ *  The clean claim is guarded: it is made ONLY when `uncommitted` was reported as 0 AND both
+ *  upstream counters were reported at all — `null` counts as reported (it is the explicit "no
+ *  upstream" answer), `undefined` does not. A status that never reported its counters therefore
+ *  yields NO flags rather than a green "clean ✓" the caller never earned. */
+export function gitFlags(status) {
+    const behind = status?.behind;
+    const uncommitted = status?.uncommitted;
+    const unpushed = status?.unpushed;
+    const flags = [];
+    if (isCount(behind) && behind > 0)
+        flags.push({ label: `${behind}↓ behind`, tone: "warn" });
+    if (isCount(uncommitted) && uncommitted > 0) {
+        flags.push({ label: `${uncommitted} uncommitted`, tone: "warn" });
+    }
+    if (isCount(unpushed) && unpushed > 0)
+        flags.push({ label: `${unpushed} unpushed`, tone: "error" });
+    if (flags.length > 0)
+        return flags;
+    const reported = (n) => n === null || isCount(n);
+    const clean = isCount(uncommitted) && uncommitted === 0 && reported(behind) && reported(unpushed);
+    return clean ? [{ label: GIT_CLEAN_LABEL, tone: "ok" }] : [];
+}
+/** Every class the chip renders, root and elements — the bindings import these rather than
+ *  spelling the strings themselves, so the two frameworks cannot drift apart on a rename. */
+export const GIT_CHIP_PARTS = {
+    root: "my-gitchip",
+    branch: "my-gitchip__branch",
+    flags: "my-gitchip__flags",
+    flag: "my-gitchip__flag",
+    note: "my-gitchip__note",
+    stale: "my-gitchip__stale",
+};
+/** Root class: base + the unavailable/stale modifiers. */
+export function gitChipClass(state = {}) {
+    const base = GIT_CHIP_PARTS.root;
+    let cls = base;
+    if (state.unavailable === true)
+        cls += ` ${base}--unavailable`;
+    if (state.stale === true)
+        cls += ` ${base}--stale`;
+    return cls;
+}
+/** Flag badge class: base + tone modifier (always present — the tone IS the flag's meaning). */
+export function gitFlagClass(tone) {
+    const base = GIT_CHIP_PARTS.flag;
+    return `${base} ${base}--${tone}`;
+}
+/** The unavailable arm's sentence: a caller-supplied reason wins; else the loading line while the
+ *  first read is in flight; else the neutral default. Never describes the tree. */
+export function gitChipNote(o = {}) {
+    const note = o.unavailableNote;
+    if (typeof note === "string" && note.trim().length > 0)
+        return note;
+    return o.loading === true ? GIT_LOADING_NOTE : GIT_UNAVAILABLE_NOTE;
+}

package/dist/logic/save-bar.d.ts

@@ -0,0 +1,39 @@
+/** The separator between the bold "N unsaved change(s)" count and the changed-field list. */
+export declare const SAVE_BAR_SEP = " \u00B7 ";
+/** Design-card copy for the two actions (ds/layouts-settings.html). Both are overridable per
+ *  surface — the reference product's settings page says "Save locally" because its save writes to
+ *  the local container, not the card's "Save & apply". */
+export declare const SAVE_BAR_DISCARD_LABEL = "Discard";
+export declare const SAVE_BAR_SAVE_LABEL = "Save & apply";
+export interface SaveBarNote {
+    /** How many fields are dirty. `0` ⇒ the bar must not be shown at all (see `saveBarDirty`). */
+    count: number;
+    /** The bold lead-in: `1 unsaved change` / `3 unsaved changes`. */
+    countLabel: string;
+    /** The changed-field list that follows the separator: `Base URL, Harness`. */
+    detail: string;
+    /** The full visible sentence, `countLabel + SAVE_BAR_SEP + detail`. Empty `detail` ⇒ just the
+     *  count (never a dangling separator). */
+    text: string;
+}
+/** Compose the save bar's note from the list of changed-field labels. Pluralization is decided
+ *  here, once, for both bindings. Non-string / blank entries are dropped rather than rendered as
+ *  `undefined` in the list — but they are dropped BEFORE the count, so the count always equals the
+ *  number of fields actually named. */
+export declare function saveBarNote(changed: readonly string[]): SaveBarNote;
+/** The card's "the save bar slides up only when dirty" rule, as a predicate. The bindings return
+ *  `null` for a not-dirty bar so no surface can ever render "0 unsaved changes" next to a live
+ *  Save button. */
+export declare function saveBarDirty(changed: readonly string[]): boolean;
+/** Every class the bar renders, root and elements. The bindings import these rather than spelling
+ *  the strings themselves, so a rename cannot land in one framework and not the other, and the
+ *  stylesheet test can enumerate the parts instead of restating a hand-written list. */
+export declare const SAVE_BAR_PARTS: {
+    readonly root: "my-savebar";
+    readonly note: "my-savebar__note";
+    readonly count: "my-savebar__count";
+    readonly actions: "my-savebar__actions";
+};
+/** Root class for the bar. No tone axis — the modifier space is reserved for the caller's own
+ *  passthrough class, which the bindings append. */
+export declare function saveBarClass(): string;

package/dist/logic/save-bar.js

@@ -0,0 +1,54 @@
+// @mythicalos/ui-core — the dirty-state save bar's pure text composition + class derivation
+// (ds/layouts-settings.html: the bar pinned to the bottom of the settings screen —
+// `1 unsaved change · Base URL` on the left, Discard + the page's single primary on the right).
+//
+// Extracted from the reference implementation in the reference product's settings/projects pages,
+// which took a `(keyof MythicalConfig)[]` — a product config's key union. That product coupling is
+// lifted out here: the atom takes plain `string[]` field labels and composes the same sentence.
+//
+// The count/plural derivation and the separator live here (not in the bindings) so the Preact and
+// React renders can never drift, and so a consumer can assert the exact visible sentence without a
+// DOM — the same contract `composeToastText` holds for the toast.
+/** The separator between the bold "N unsaved change(s)" count and the changed-field list. */
+export const SAVE_BAR_SEP = " · ";
+/** Design-card copy for the two actions (ds/layouts-settings.html). Both are overridable per
+ *  surface — the reference product's settings page says "Save locally" because its save writes to
+ *  the local container, not the card's "Save & apply". */
+export const SAVE_BAR_DISCARD_LABEL = "Discard";
+export const SAVE_BAR_SAVE_LABEL = "Save & apply";
+/** Compose the save bar's note from the list of changed-field labels. Pluralization is decided
+ *  here, once, for both bindings. Non-string / blank entries are dropped rather than rendered as
+ *  `undefined` in the list — but they are dropped BEFORE the count, so the count always equals the
+ *  number of fields actually named. */
+export function saveBarNote(changed) {
+    const fields = (changed ?? []).filter((f) => typeof f === "string" && f.trim().length > 0);
+    const count = fields.length;
+    const countLabel = `${count} unsaved ${count === 1 ? "change" : "changes"}`;
+    const detail = fields.join(", ");
+    return {
+        count,
+        countLabel,
+        detail,
+        text: detail.length > 0 ? `${countLabel}${SAVE_BAR_SEP}${detail}` : countLabel,
+    };
+}
+/** The card's "the save bar slides up only when dirty" rule, as a predicate. The bindings return
+ *  `null` for a not-dirty bar so no surface can ever render "0 unsaved changes" next to a live
+ *  Save button. */
+export function saveBarDirty(changed) {
+    return saveBarNote(changed).count > 0;
+}
+/** Every class the bar renders, root and elements. The bindings import these rather than spelling
+ *  the strings themselves, so a rename cannot land in one framework and not the other, and the
+ *  stylesheet test can enumerate the parts instead of restating a hand-written list. */
+export const SAVE_BAR_PARTS = {
+    root: "my-savebar",
+    note: "my-savebar__note",
+    count: "my-savebar__count",
+    actions: "my-savebar__actions",
+};
+/** Root class for the bar. No tone axis — the modifier space is reserved for the caller's own
+ *  passthrough class, which the bindings append. */
+export function saveBarClass() {
+    return SAVE_BAR_PARTS.root;
+}

package/dist/logic/stat-tiles.d.ts

@@ -0,0 +1,49 @@
+/** Tile tone. `accent` is the design card's "brag" number (`.tile.save .v`); `warn`/`error` are the
+ *  gauge-band tint. Absent ⇒ a plain tile. */
+export type StatTileTone = "accent" | "warn" | "error";
+export interface StatTile {
+    /** Uppercase micro key, e.g. `tokens in`. */
+    label: string;
+    /** The already-formatted value — use the formatters below, or supply your own string. */
+    value: string;
+    /** Mono sub-caption under the value, e.g. `this session`. */
+    sub?: string;
+    tone?: StatTileTone;
+}
+/** The value shown when a number is absent or not finite. An em dash — NEVER a zero. */
+export declare const STAT_TILE_EMPTY = "\u2014";
+/** Unicode minus (U+2212), not an ASCII hyphen: it matches the digit metrics of the tabular-nums
+ *  mono face the tile value is set in. */
+export declare const STAT_TILE_MINUS = "\u2212";
+/** Every class the row renders, containers and elements — the bindings import these rather than
+ *  spelling the strings themselves, so the two frameworks cannot drift apart on a rename. */
+export declare const STAT_TILE_PARTS: {
+    readonly row: "my-stat-tiles";
+    readonly tile: "my-stat-tile";
+    readonly label: "my-stat-tile__label";
+    readonly value: "my-stat-tile__value";
+    readonly sub: "my-stat-tile__sub";
+};
+/** Row container class. */
+export declare function statTilesClass(): string;
+/** Tile class: base + optional tone modifier. */
+export declare function statTileClass(tone?: StatTileTone): string;
+/** Compact count: `500`, `12.8k`, `230k`, `1.5M`; negatives take the Unicode minus (`−212k`).
+ *  Absent/non-finite ⇒ `STAT_TILE_EMPTY`.
+ *
+ *  The unit is chosen from the ROUNDED value, not the raw one: rounding first and picking the unit
+ *  second would render `999.5` as `1000` and `999_999` as `1000k` — values that are noncanonical
+ *  for the scale and sit right in the middle of a normal token count. Each rung promotes to the
+ *  next when its own rounding carries it to 1000. `M` is the top rung — the design card defines no
+ *  unit above it, so a billion reads `1000M`, not `1B`. */
+export declare function formatStatCompact(n: number | null | undefined): string;
+/** Grouped count: `1,204,551` — the design card's tokens-in/out format. Deliberately NOT
+ *  `toLocaleString()`: the card's grouping is a fixed visual (comma every three digits, mono
+ *  tabular-nums), and a host locale must not silently turn it into `1.204.551`.
+ *  Absent/non-finite ⇒ `STAT_TILE_EMPTY`. */
+export declare function formatStatCount(n: number | null | undefined): string;
+/** USD: `$4.18`, always two decimals. Absent/non-finite ⇒ `STAT_TILE_EMPTY`. */
+export declare function formatStatUsd(n: number | null | undefined): string;
+/** Percent: `71%` by default, `94.5%` at `digits: 1` — the design card shows both forms.
+ *  Absent/non-finite ⇒ `STAT_TILE_EMPTY`. */
+export declare function formatStatPercent(n: number | null | undefined, digits?: number): string;

package/dist/logic/stat-tiles.js

@@ -0,0 +1,102 @@
+// @mythicalos/ui-core — the stat-tile row's tone→class derivation + the value formatters
+// (ds/components-stat-tiles.html: a flex-wrap row of bordered tiles, each an uppercase micro
+// "key", a big mono tabular-nums value, and a mono sub-caption; the "brag" tile paints its value
+// --my-accent-strong).
+//
+// Extracted from the reference implementation in the reference product's session detail pane. That
+// version took the product's `SessionVm` and hard-coded the five session tiles (tokens in/out,
+// prompt cache, cost, spine savings) INSIDE the component. That composition is the product's
+// domain, not the design system's: the atom here takes an already-composed `StatTile[]`, so a
+// consumer's view-model decides which tiles exist and in what order.
+//
+// What DID come along, because it is design and not product:
+//   - the "—" placeholder: an absent value renders the em dash, never a fabricated `0` / `$0.00`
+//     (partial data renders partially — never all-or-nothing),
+//   - the Unicode minus (U+2212, not a hyphen) on negative compact counts — the design card's
+//     spine-savings tile literally reads `−212k`,
+//   - the warn/error tone tint, which the reference drove off the context gauge's own 75/90 bands
+//     (token rule #4) — the thresholds themselves stay with the caller, only the tint is here.
+/** The value shown when a number is absent or not finite. An em dash — NEVER a zero. */
+export const STAT_TILE_EMPTY = "—";
+/** Unicode minus (U+2212), not an ASCII hyphen: it matches the digit metrics of the tabular-nums
+ *  mono face the tile value is set in. */
+export const STAT_TILE_MINUS = "−";
+/** Every class the row renders, containers and elements — the bindings import these rather than
+ *  spelling the strings themselves, so the two frameworks cannot drift apart on a rename. */
+export const STAT_TILE_PARTS = {
+    row: "my-stat-tiles",
+    tile: "my-stat-tile",
+    label: "my-stat-tile__label",
+    value: "my-stat-tile__value",
+    sub: "my-stat-tile__sub",
+};
+/** Row container class. */
+export function statTilesClass() {
+    return STAT_TILE_PARTS.row;
+}
+/** Tile class: base + optional tone modifier. */
+export function statTileClass(tone) {
+    const base = STAT_TILE_PARTS.tile;
+    return tone === undefined ? base : `${base} ${base}--${tone}`;
+}
+/** True only for a real, finite number — `undefined`, `null` and `NaN`/`Infinity` all fall through
+ *  to `STAT_TILE_EMPTY` rather than being coerced. */
+function isNum(n) {
+    return typeof n === "number" && Number.isFinite(n);
+}
+/** Strip a trailing `.0` so `230.0` → `230` while `12.8` stays `12.8`. */
+function stripZero(s) {
+    return s.endsWith(".0") ? s.slice(0, -2) : s;
+}
+/** Sign prefix for an already-rounded magnitude string. A negative input whose ROUNDED magnitude is
+ *  zero gets no sign — `−0` / `−$0.00` would be a lie about the direction of a value that landed on
+ *  zero at display precision. */
+function signed(n, body, zero) {
+    return n < 0 && body !== zero ? STAT_TILE_MINUS + body : body;
+}
+/** Compact count: `500`, `12.8k`, `230k`, `1.5M`; negatives take the Unicode minus (`−212k`).
+ *  Absent/non-finite ⇒ `STAT_TILE_EMPTY`.
+ *
+ *  The unit is chosen from the ROUNDED value, not the raw one: rounding first and picking the unit
+ *  second would render `999.5` as `1000` and `999_999` as `1000k` — values that are noncanonical
+ *  for the scale and sit right in the middle of a normal token count. Each rung promotes to the
+ *  next when its own rounding carries it to 1000. `M` is the top rung — the design card defines no
+ *  unit above it, so a billion reads `1000M`, not `1B`. */
+export function formatStatCompact(n) {
+    if (!isNum(n))
+        return STAT_TILE_EMPTY;
+    const abs = Math.abs(n);
+    let body;
+    if (Math.round(abs) < 1000)
+        body = String(Math.round(abs));
+    else if (Number((abs / 1000).toFixed(1)) < 1000)
+        body = `${stripZero((abs / 1000).toFixed(1))}k`;
+    else
+        body = `${stripZero((abs / 1_000_000).toFixed(1))}M`;
+    return signed(n, body, "0");
+}
+/** Grouped count: `1,204,551` — the design card's tokens-in/out format. Deliberately NOT
+ *  `toLocaleString()`: the card's grouping is a fixed visual (comma every three digits, mono
+ *  tabular-nums), and a host locale must not silently turn it into `1.204.551`.
+ *  Absent/non-finite ⇒ `STAT_TILE_EMPTY`. */
+export function formatStatCount(n) {
+    if (!isNum(n))
+        return STAT_TILE_EMPTY;
+    const grouped = String(Math.round(Math.abs(n))).replace(/\B(?=(\d{3})+(?!\d))/g, ",");
+    return signed(n, grouped, "0");
+}
+/** USD: `$4.18`, always two decimals. Absent/non-finite ⇒ `STAT_TILE_EMPTY`. */
+export function formatStatUsd(n) {
+    if (!isNum(n))
+        return STAT_TILE_EMPTY;
+    return signed(n, `$${Math.abs(n).toFixed(2)}`, "$0.00");
+}
+/** Percent: `71%` by default, `94.5%` at `digits: 1` — the design card shows both forms.
+ *  Absent/non-finite ⇒ `STAT_TILE_EMPTY`. */
+export function formatStatPercent(n, digits = 0) {
+    if (!isNum(n))
+        return STAT_TILE_EMPTY;
+    const safeDigits = Math.max(0, Math.min(4, Math.trunc(digits)));
+    const body = `${Math.abs(n).toFixed(safeDigits)}%`;
+    return signed(n, body, `${(0).toFixed(safeDigits)}%`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mythicalos/ui-core",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "mythicalOS framework-agnostic UI core — the pure logic (class derivation, poll scheduling, dialog/toast/gauge helpers), the token-driven component stylesheet, and the <mythical-select> form-associated web component. Zero framework runtime; the Preact and React bindings derive identical output from this package. Apache-2.0.",
   "type": "module",
   "license": "Apache-2.0",

package/src/select/mythical-select.js

@@ -224,7 +224,11 @@ button:focus-visible{outline:2px solid var(--my-accent,#0F6B66);outline-offset:2
 #label:empty::before{content:"\\00a0"}
 .car{flex:none;color:var(--my-muted,#5A5F6A);transition:transform var(--my-t-fast,120ms ease)}
 :host([data-open]) .car{transform:rotate(180deg)}
-#pop{position:absolute;top:calc(100% + 6px);left:0;z-index:30;min-width:100%;max-height:280px;
+/* Pinned to BOTH edges with border-box sizing: under the old
+   `min-width:100%` + content-box, the 6px padding and 1px border were added
+   OUTSIDE the 100%, so the popup rendered 14px wider than its own control. */
+#pop{position:absolute;top:calc(100% + 6px);left:0;right:0;z-index:30;width:100%;
+  box-sizing:border-box;max-height:280px;
   overflow:auto;overscroll-behavior:contain;padding:6px;background:var(--my-surface,#fff);
   border:1px solid var(--my-border,#E7E3DB);border-radius:var(--my-r-card,10px);
   box-shadow:var(--my-shadow-modal,0 16px 48px rgba(22,24,29,.16));

package/styles.css

@@ -327,3 +327,101 @@ a:focus-visible, .link:focus-visible, .is-focus {
 /* design rule 6 — the shared focus ring, restated rather than added to the BASE selector list
    above for the same reason the rules above live here */
 .input-reveal__btn:focus-visible { outline: 2px solid var(--my-accent); outline-offset: 2px; }
+
+/* ══════════════════════════════════════════════════════════════════════════════════════════
+   SMALL ATOMS — save bar · stat tiles · git status chip. Each was registered in the design
+   system but implemented only inside one product; these rules are taken from the cards
+   (ds/layouts-settings.html, ds/components-stat-tiles.html, ds/components-git-chip.html) with
+   colors/font-sizes remapped onto canonical --my-* tokens. Where the product's local sheet and
+   the card differed, the CARD wins and the delta is noted inline.
+   ══════════════════════════════════════════════════════════════════════════════════════════ */
+
+/* save bar (ds/layouts-settings.html `.save`) — full-bleed bottom, slides up only when dirty.
+   The card draws it `position:absolute` inside its own bordered screen frame; a packaged atom has
+   no such frame to anchor to, so it is `fixed` to the viewport (what the reference product's
+   sheet does too) — a consumer that needs it scoped to a pane overrides `position` via the
+   passthrough class. Padding is the card's `9px 16px`; the product's own sheet insets it to 24px
+   horizontally, which a consumer can restore from its own sheet. */
+.my-savebar {
+  position: fixed; left: 0; right: 0; bottom: 0; z-index: 30;
+  background: var(--my-surface); border-top: 1px solid var(--my-border);
+  display: flex; align-items: center; gap: 10px;
+  padding: 9px var(--my-sp-4); font-size: var(--my-fs-caption); /* the card's 9px 16px */
+  animation: my-savebar-up 180ms ease-out; /* the card's "slides up (180ms)" */
+}
+@keyframes my-savebar-up { from { transform: translateY(100%); } }
+@media (prefers-reduced-motion: reduce) { .my-savebar { animation: none; } }
+.my-savebar__note { color: var(--my-muted); }
+.my-savebar__count { color: var(--my-ink); font-weight: var(--my-fw-bold); }
+.my-savebar__actions { margin-left: auto; display: flex; gap: var(--my-sp-2); }
+
+/* stat tiles (ds/components-stat-tiles.html `.tiles`/`.tile`) — mono, tabular-nums, micro key +
+   mono sub-caption. The card sizes tiles by content off a 112px floor; the reference product's
+   sheet additionally stretches them with `flex: 1`, which a consumer can restore from its own
+   sheet (`.my-stat-tiles > .my-stat-tile { flex: 1 }`). */
+.my-stat-tiles { display: flex; gap: 10px; flex-wrap: wrap; }
+.my-stat-tile {
+  min-width: 112px; background: var(--my-surface);
+  border: 1px solid var(--my-border); border-radius: var(--my-r-card); padding: 10px 12px;
+}
+.my-stat-tile__label {
+  font-size: var(--my-fs-micro); /* card: 10px, no exact token step */
+  font-weight: var(--my-fw-bold); text-transform: uppercase; letter-spacing: .4px;
+  color: var(--my-muted);
+}
+.my-stat-tile__value {
+  font-family: var(--my-font-mono);
+  font-size: var(--my-fs-body-lg); /* card: 17px, nearest token step */
+  font-weight: var(--my-fw-bold); font-variant-numeric: tabular-nums; margin-top: 2px;
+}
+.my-stat-tile__sub {
+  font-family: var(--my-font-mono);
+  font-size: var(--my-fs-micro); /* card: 10.5px, no exact token step */
+  color: var(--my-muted);
+}
+/* the card's "brag" number (`.tile.save .v` → --my-accent-strong) */
+.my-stat-tile--accent .my-stat-tile__value { color: var(--my-accent-strong); }
+/* band tint (token rule #4 thresholds live with the caller, only the tint is here) */
+.my-stat-tile--warn { border-color: var(--my-warn); }
+.my-stat-tile--warn .my-stat-tile__value { color: var(--my-warn); }
+.my-stat-tile--error { border-color: var(--my-error); }
+.my-stat-tile--error .my-stat-tile__value { color: var(--my-error); }
+
+/* git status chip (ds/components-git-chip.html `.gitchip`/`.gitflag`) — a bordered inline mono
+   chip. The flags are the card's own squared 4px badge, NOT the pill `.my-chip`: inside a mono
+   chip the card gives them a tighter, squared shape, and design rule #10 reserves the pill for
+   stand-alone non-interactive tags.
+
+   Three deliberate deltas from the card, all recorded here (and pinned by
+   test/css-small-atoms.test.ts) rather than left to be discovered:
+     - `flex-wrap: wrap` on the chip and its flag group. The card demonstrates the chip inside a
+       fixed 820px panel where it cannot run out of room; a packaged atom renders at whatever width
+       the consumer gives it, and a long branch name plus three flags must wrap rather than
+       overflow its container.
+     - the branch keeps the card's inherited weight (NOT bold). The product's local sheet bolds it;
+       the card does not, so the card wins.
+     - the flag weight is `--my-fw-bold` (650), where the card's literal is 700. There is no 700
+       step on the canonical --my-fw-* scale, and the additions section above already normalizes
+       badge weights onto the nearest token (`.my-chip` does exactly this). */
+.my-gitchip {
+  display: inline-flex; gap: 10px; align-items: center; flex-wrap: wrap; /* delta 1 */
+  font-family: var(--my-font-mono); font-size: var(--my-fs-caption);
+  border: 1px solid var(--my-border); border-radius: var(--my-r-control);
+  padding: 6px 10px; background: var(--my-surface);
+}
+.my-gitchip__branch { color: var(--my-ink); } /* delta 2 — card weight, not the product's bold */
+.my-gitchip__flags { display: inline-flex; gap: 6px; flex-wrap: wrap; align-items: center; }
+.my-gitchip__flag {
+  font-size: var(--my-fs-micro); /* card: 10px, no exact token step */
+  font-weight: var(--my-fw-bold); /* delta 3 — card: 700, no exact token step */
+  letter-spacing: .3px; border-radius: 4px; padding: 2px 6px;
+}
+.my-gitchip__flag--warn  { background: var(--my-warn-soft);  color: var(--my-warn); }
+.my-gitchip__flag--error { background: var(--my-error-soft); color: var(--my-error); }
+.my-gitchip__flag--ok    { background: var(--my-ok-soft);    color: var(--my-ok); }
+/* the honest unavailable arm: the branch slot is muted and the note carries the reason in UI type */
+.my-gitchip--unavailable .my-gitchip__branch { color: var(--my-muted); }
+.my-gitchip__note { font-family: var(--my-font-ui); color: var(--my-muted); }
+/* a retained (not current) status — flagged on BOTH arms */
+.my-gitchip--stale { border-color: var(--my-warn); }
+.my-gitchip__stale { color: var(--my-warn); font-size: var(--my-fs-micro); }