@mythicalos/ui-core 0.2.1 → 0.3.0

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/popover.d.ts

@@ -0,0 +1,242 @@
+/** Trigger caret (design card: `<span class="car">▾</span>`). */
+export declare const POPOVER_CARET = "\u25BE";
+/** Selected-item marker (design card: "✓ marks current"). */
+export declare const POPOVER_CHECK = "\u2713";
+/** Anchor gap in px — the design card's `top: calc(100% + 6px)`. Mirrored in styles.css. */
+export declare const POPOVER_GAP_PX = 6;
+/** Extra breathing room the flip test demands beyond the gap (mythical-select uses `height + 8`
+ * for a 6px gap — i.e. gap + 2). */
+export declare const POPOVER_BREATHING_PX = 2;
+/** Trigger value shown when nothing is selected (the em-dash placeholder, as in the product's
+ * hand-rolled selector) — never a fabricated item label. */
+export declare const POPOVER_EMPTY_VALUE = "\u2014";
+/** One row of the popover's single-select menu. */
+export interface PopoverItem {
+    /** Stable identity handed back to `onSelect` — never the array index. */
+    key: string;
+    label: string;
+    /** Marks the current choice: gets the ✓ and `aria-checked="true"`. */
+    selected?: boolean;
+    /** Rendered, focusable-by-arrow? No — skipped by roving focus and inert on click. */
+    disabled?: boolean;
+}
+export type PopoverPlacement = "below" | "above";
+export type PopoverAlign = "start" | "end";
+export interface PopoverPosition {
+    placement: PopoverPlacement;
+    align: PopoverAlign;
+}
+/** The pre-measurement position: the design card's own (anchored below, left-aligned). A binding
+ * renders this on the first open frame, then corrects it once the panel can be measured. */
+export declare const POPOVER_DEFAULT_POSITION: PopoverPosition;
+/** The subset of a DOMRect this module needs (so callers can pass a real rect or a plain object). */
+export interface PopoverRect {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+export interface PopoverSize {
+    width: number;
+    height: number;
+}
+export interface PopoverViewport {
+    width: number;
+    height: number;
+}
+/**
+ * Viewport-aware vertical placement. Flips UP only when the panel would clip off the bottom AND it
+ * genuinely fits above — a panel taller than both gaps stays `below` (scrolling down to it beats
+ * clipping it against the top edge, and it matches <mythical-select>'s behaviour exactly).
+ */
+export declare function resolvePopoverPlacement(anchor: PopoverRect, panelHeight: number, viewport: PopoverViewport, gap?: number): PopoverPlacement;
+/**
+ * Viewport-aware horizontal alignment. The panel is start-aligned (design card: `left: 0`) and
+ * switches to end-aligned only when start does NOT fit and end does.
+ *
+ * "Fits" means BOTH resulting edges are inside the viewport, on both branches — an alignment pins
+ * one panel edge to the matching anchor edge, so an anchor that is itself partly off-screen drags
+ * the panel off with it. Testing only the far edge is wrong in each direction symmetrically:
+ * start-aligning an anchor hanging off the LEFT clips the panel's left edge even though its right
+ * edge is comfortable, and end-aligning an anchor hanging off the RIGHT clips its right edge even
+ * though `right - panelWidth >= 0`. A panel that fits neither way stays `start` — flipping would
+ * only trade one overflow for the other.
+ */
+export declare function resolvePopoverAlign(anchor: PopoverRect, panelWidth: number, viewport: PopoverViewport): PopoverAlign;
+/** Both axes at once — what a binding calls from its post-open measurement effect. */
+export declare function resolvePopoverPosition(anchor: PopoverRect, panel: PopoverSize, viewport: PopoverViewport, gap?: number): PopoverPosition;
+/** True when two positions describe the same placement — lets a binding skip a redundant
+ * re-render after re-measuring (and, more importantly, not loop measure→setState→measure). */
+export declare function samePopoverPosition(a: PopoverPosition, b: PopoverPosition): boolean;
+/**
+ * EVERY class name this component family renders — the derived ones the functions below compose
+ * AND the purely structural ones a binding puts on a wrapper/span. One source, so a binding cannot
+ * invent, misspell, or quietly re-style a class, and the Preact and React siblings cannot drift on
+ * markup either. (The rest of this package's atoms inline their structural classes in both
+ * bindings; the popover has more of them than any other atom, so it earns the map.)
+ */
+export declare const POPOVER_CLASS: {
+    readonly anchor: "my-pop-anchor";
+    readonly trigger: "my-pop-trigger";
+    readonly triggerLabel: "my-pop-trigger__label";
+    readonly triggerValue: "my-pop-trigger__value";
+    readonly triggerCaret: "my-pop-trigger__caret";
+    readonly panel: "my-pop";
+    readonly panelAbove: "my-pop--above";
+    readonly panelEnd: "my-pop--end";
+    readonly head: "my-pop__head";
+    readonly title: "my-pop__title";
+    readonly caption: "my-pop__caption";
+    readonly menu: "my-pop__menu";
+    readonly item: "my-pop__item";
+    readonly itemLabel: "my-pop__label";
+    readonly itemCheck: "my-pop__check";
+    readonly divider: "my-pop__div";
+    readonly foot: "my-pop__foot";
+    readonly isOpen: "is-open";
+    readonly isSelected: "is-selected";
+    readonly isDisabled: "is-disabled";
+};
+export interface PopoverTriggerState {
+    open?: boolean;
+    disabled?: boolean;
+}
+/** Trigger class list. Shape rule 10: the trigger is clickable, so styles.css gives it
+ * `--my-r-control` — never the pill radius. */
+export declare function popoverTriggerClass(s?: PopoverTriggerState): string;
+/** Panel class list; the flip/align modifiers are the only thing position changes. */
+export declare function popoverPanelClass(pos?: PopoverPosition): string;
+/** Menu-row class list. */
+export declare function popoverItemClass(item?: Pick<PopoverItem, "selected" | "disabled">): string;
+export interface PopoverIds {
+    trigger: string;
+    /** The visual panel — the surface that carries the border/shadow and the optional head/footer. */
+    panel: string;
+    /** The `role="menu"` element NESTED in the panel. A menu may only own menuitem-family, group and
+     * separator children, so the heading and the caller's footer are siblings of this element, not
+     * children of it — putting them inside would make the menu's owned content invalid and let
+     * assistive tech drop or mis-announce them. */
+    menu: string;
+    /** The heading, when there is one — it names the menu in place of the trigger. */
+    title: string;
+}
+/** Stable, collision-free id set derived from one caller-supplied base id. */
+export declare function popoverIds(baseId: string): PopoverIds;
+export interface PopoverTriggerAria {
+    id: string;
+    "aria-haspopup": "menu";
+    "aria-expanded": "true" | "false";
+    /** The MENU (not the panel wrapper) it controls, and only while open — the element does not
+     * exist when closed, and pointing at a missing id is an authoring error assistive tech reports. */
+    "aria-controls": string | undefined;
+}
+export declare function popoverTriggerAria(open: boolean, ids: PopoverIds): PopoverTriggerAria;
+export interface PopoverPanelAria {
+    id: string;
+}
+/** The visual panel: the surface, deliberately WITHOUT a role. It holds the optional heading and
+ * the caller's footer, which a `menu` may not own. */
+export declare function popoverPanelAria(ids: PopoverIds): PopoverPanelAria;
+export interface PopoverMenuAria {
+    id: string;
+    role: "menu";
+    "aria-labelledby": string;
+}
+/** The nested menu, which owns ONLY the `menuitemradio` rows. Named by the heading when there is
+ * one (the more specific label), otherwise by the trigger. */
+export declare function popoverMenuAria(ids: PopoverIds, titled: boolean): PopoverMenuAria;
+/**
+ * The caret and the ✓ are pure decoration: the trigger's `aria-expanded` and the row's
+ * `aria-checked` already convey both states, so reading the glyphs would duplicate them. Lives here
+ * rather than inline in each binding so neither can quietly un-hide one.
+ */
+export declare const POPOVER_DECORATIVE_ARIA: {
+    readonly "aria-hidden": "true";
+};
+/** The rule between the menu and the caller's footer — a real separator, not a styled `<div>`. */
+export declare const POPOVER_SEPARATOR_ARIA: {
+    readonly role: "separator";
+};
+export interface PopoverItemAria {
+    /** Single-select menu ⇒ radio semantics, so a screen reader announces "1 of N, checked". */
+    role: "menuitemradio";
+    "aria-checked": "true" | "false";
+    "aria-disabled": "true" | undefined;
+}
+export declare function popoverItemAria(item: Pick<PopoverItem, "selected" | "disabled">): PopoverItemAria;
+/** What a key pressed on the CLOSED trigger means. Enter/Space are deliberately absent: the
+ * trigger is a real `<button>`, so the browser already synthesises a click from them — handling
+ * them here too would toggle twice. */
+export type PopoverTriggerKeyAction = "open-first" | "open-last" | null;
+export declare function popoverTriggerKeyAction(key: string): PopoverTriggerKeyAction;
+/**
+ * What a key pressed INSIDE the open panel means.
+ *  - `close`   — Escape: close and pull focus back to the trigger (never strand it on <body>).
+ *  - `dismiss` — Tab: close, but let the browser move focus onward normally.
+ *  - the rest  — roving focus.
+ */
+export type PopoverPanelKeyAction = "close" | "dismiss" | "next" | "prev" | "first" | "last" | null;
+export declare function popoverPanelKeyAction(key: string): PopoverPanelKeyAction;
+/** Should the binding call `preventDefault()`? Everything we act on, except `dismiss` — Tab MUST
+ * keep its native behaviour or the popover becomes a focus trap. */
+export declare function popoverKeyHandled(action: PopoverPanelKeyAction): boolean;
+/**
+ * Does this action apply to the element that currently has focus?
+ *
+ * Dismissal (Escape / Tab) applies from ANYWHERE inside the popover — including the caller's
+ * footer content, where Escape must still close. Roving (arrows / Home / End) applies ONLY when
+ * focus is on a menu row or on the panel fallback. That distinction is load-bearing, not tidiness:
+ * a footer control is arbitrary caller markup, so swallowing Home/End there would steal a text
+ * input's caret keys, and swallowing an arrow would yank focus out of the footer and into the menu.
+ * The binding supplies the one thing this module cannot compute — whether the focused element is a
+ * roving surface.
+ */
+export declare function popoverAppliesToFocus(action: PopoverPanelKeyAction, focusOnRovingSurface: boolean): boolean;
+/** Index of the first enabled item scanning forward (`dir` 1) or backward (`dir` -1); -1 if every
+ * item is disabled (or the list is empty). */
+export declare function edgePopoverIndex(items: readonly PopoverItem[], dir?: 1 | -1): number;
+/** The next enabled index from `from` in `dir`, wrapping. Returns -1 when nothing is enabled and
+ * `from` itself when it is the ONLY enabled row (a wrap that lands back where it started). */
+export declare function stepPopoverIndex(items: readonly PopoverItem[], from: number, dir: 1 | -1): number;
+/**
+ * Where focus lands when the panel opens: the selected row if it is focusable, else the first
+ * enabled one. A selected-but-disabled row does not swallow focus.
+ */
+export declare function initialPopoverIndex(items: readonly PopoverItem[]): number;
+/**
+ * The single entry point a binding's keydown handler calls: maps a panel key action + the current
+ * focused index to the next focused index. Non-navigation actions (and a null action) leave the
+ * index untouched, so the caller never has to branch on the action twice.
+ *
+ * `current < 0` means "focus is in the panel but not on a row" (an all-disabled or empty list, or
+ * a click that landed on the panel's padding). From there Down means the FIRST enabled row and Up
+ * means the LAST — not a wrap arithmetic accident off index -1.
+ */
+export declare function resolvePopoverIndex(action: PopoverPanelKeyAction, items: readonly PopoverItem[], current: number): number;
+/**
+ * Is an optional slot (heading, caption, footer) worth rendering its chrome?
+ *
+ * `undefined`, `null`, `false` and `""` are all values BOTH frameworks render as nothing, and the
+ * idiomatic conditional slot is `footer={enabled && <Action />}` — which passes `false`, not
+ * `undefined`, when disabled. Testing `!== undefined` would leave an orphan separator and an empty
+ * box behind it, and an empty heading would leave the menu's `aria-labelledby` pointing at an
+ * element with no text. Shared here so both bindings apply the same rule.
+ */
+export declare function popoverHasSlotContent(slot: unknown): boolean;
+export interface PopoverTriggerText {
+    /** The static prefix ("review lane:") — null when the caller supplies none. */
+    label: string | null;
+    /** The current selection's label, or the em-dash placeholder. Never invented. */
+    value: string;
+}
+export interface PopoverTriggerTextOptions {
+    label?: string;
+    /** Overrides {@link POPOVER_EMPTY_VALUE} for the no-selection case. */
+    placeholder?: string;
+}
+/**
+ * The trigger face: prefix + the CURRENTLY selected item's label. Honest by construction — with no
+ * selection (or a selection that is not in the list) it shows the placeholder rather than naming an
+ * item that is not actually chosen.
+ */
+export declare function popoverTriggerText(items: readonly PopoverItem[], opts?: PopoverTriggerTextOptions): PopoverTriggerText;