@reddb-io/ui-kit 0.3.4 → 0.3.6

package/vendor/ds/kits/app/src/primitives/Pill.svelte

@@ -0,0 +1,81 @@
+<!--
+  Pill — a Primitive: it imports no other Kit component.
+
+  Optionally dismissible. The dismiss affordance is a plain <button> rather
+  than the Kit's Button: reaching for Button here would make Pill a Composite
+  and drag a whole control's variants into a 20px target that only ever needs
+  to inherit the Pill's own colour. The mechanical Taxonomy test is what keeps
+  that decision honest rather than aesthetic.
+-->
+<script lang="ts">
+  import type { PillContract } from "../core/contracts/pill";
+  import type { Tone } from "@reddb-io/design-system/base";
+  import type { Snippet } from "svelte";
+  import type { HTMLAttributes } from "svelte/elements";
+  import { quietControl, warnDeprecated } from "@reddb-io/design-system/base";
+  import {
+    pill,
+    pillDismiss,
+    type DeprecatedPillVariant,
+    type PillSize,
+    type PillVariant,
+  } from "./pill.variants";
+
+  interface Props extends PillContract, Omit<HTMLAttributes<HTMLSpanElement>, keyof PillContract | "class"> {
+    /**
+     * When given, the Pill renders a dismiss affordance and calls this. Absent,
+     * it renders none — a Pill nobody can remove should not pretend otherwise.
+     */
+    ondismiss?: () => void;
+    /** @deprecated Renamed `ondismiss` (ADR 0026); removed next release. */
+    onDismiss?: () => void;
+    /** Extra classes, merged over the variant's own. */
+    class?: string;
+    /** The Pill's label content, rendered before the dismiss affordance. */
+    children?: Snippet;
+  }
+
+  const {
+    tone = "neutral",
+    variant = "tinted",
+    size = "md",
+    ondismiss,
+    onDismiss,
+    dismissLabel = "Remove",
+    class: className,
+    children,
+    ...rest
+  }: Props = $props();
+
+  const dismiss = $derived(ondismiss ?? onDismiss);
+
+  $effect(() => {
+    if (onDismiss) warnDeprecated("Pill", "onDismiss", "ondismiss");
+    if (variant === "neutral") warnDeprecated("Pill", 'variant="neutral"', 'variant="tinted" (the default)');
+    if (variant === "primary") {
+      warnDeprecated(
+        "Pill",
+        'variant="primary"',
+        'a tone with variant="filled"; the accent fill is not a meaning',
+      );
+    }
+  });
+</script>
+
+<span
+  {...rest}
+  class={pill({ tone, variant, size, class: className })}
+  data-pill
+  data-tone={tone}
+  data-variant={variant}
+>
+  {@render children?.()}
+  {#if dismiss}
+    <button type="button" data-pill-dismiss class={quietControl({ ink: "inherit", class: pillDismiss() })} aria-label={dismissLabel} onclick={() => dismiss()}>
+      <!-- A glyph, not an icon dependency: the Kit ships no icon set yet, and
+           inventing one inside a Primitive would be a second decision hiding
+           inside this slice. -->
+      <span aria-hidden="true">&times;</span>
+    </button>
+  {/if}
+</span>

package/vendor/ds/kits/app/src/primitives/SplitView.svelte

@@ -0,0 +1,148 @@
+<!--
+  SplitView — a Primitive: it imports no other Kit component. It imports its
+  own behavior module, which is a `.ts` file and not a component, so the
+  mechanical test in test/taxonomy.test.ts reads it as what it is.
+
+  Two panes and a divider you can move, by pointer or by keyboard. The
+  arithmetic lives in split-view.behavior.ts, where it can be tested without a
+  browser; what is left here is the part that genuinely needs a DOM.
+
+  The divider is a real `role="separator"` with a tab stop and value bounds, so
+  the split is adjustable without a pointer at all — the failure mode of every
+  hand-rolled splitter, and the reason this one is in the Kit rather than in
+  each application.
+
+  `fraction` is bindable, and every move the user makes is reported through
+  `onfractionchange` (ADR 0026): an application that wants to persist the
+  split reads it, and one that does not can ignore it entirely.
+-->
+<script lang="ts">
+  import type { SplitViewContract } from "../core/contracts/splitview";
+  import type { Snippet } from "svelte";
+  import type { HTMLAttributes } from "svelte/elements";
+  import {
+    SPLIT_BOUNDS,
+    clampFraction,
+    fractionAt,
+    fractionForKey,
+    percentOf,
+    separatorOrientation,
+    type SplitOrientation,
+  } from "./split-view.behavior";
+  import { splitView } from "./split-view.variants";
+
+  interface Props extends SplitViewContract, Omit<HTMLAttributes<HTMLDivElement>, "class"> {
+    /** Called with the new fraction after each pointer or keyboard move. */
+    onfractionchange?: (fraction: number) => void;
+    /** The leading pane: left, or top. */
+    start?: Snippet;
+    /** The trailing pane: right, or bottom. */
+    end?: Snippet;
+    /** Extra classes, merged over the root slot's own. */
+    class?: string;
+  }
+
+  let {
+    orientation = "horizontal",
+    fraction = $bindable(0.5),
+    onfractionchange,
+    min = SPLIT_BOUNDS.min,
+    max = SPLIT_BOUNDS.max,
+    label = "Resize panes",
+    start,
+    end,
+    class: className,
+    ...rest
+  }: Props = $props();
+
+  let container: HTMLElement | undefined = $state();
+  let dragging = $state(false);
+
+  const bounds = $derived({ min, max });
+  const position = $derived(clampFraction(fraction, bounds));
+  const slots = $derived(splitView({ orientation, dragging }));
+
+  function grab(event: PointerEvent): void {
+    dragging = true;
+    // Capture keeps the moves coming once the pointer outruns a divider four
+    // pixels wide, which it does immediately. Where there is no pointer
+    // capture — jsdom, or a browser declining the id — the root handlers keep
+    // the drag alive across either pane while the pointer remains in the split.
+    try {
+      (event.currentTarget as HTMLElement).setPointerCapture?.(event.pointerId);
+    } catch {
+      /* nothing to capture with; the move handler still runs. */
+    }
+  }
+
+  function move(event: PointerEvent): void {
+    if (!dragging || !container) return;
+    const box = container.getBoundingClientRect();
+    const next =
+      orientation === "horizontal"
+        ? fractionAt(event.clientX - box.left, box.width, bounds)
+        : fractionAt(event.clientY - box.top, box.height, bounds);
+    // A move the container cannot measure leaves the divider alone rather than
+    // slamming it to an edge.
+    if (next === null) return;
+    commit(next);
+  }
+
+  function commit(next: number): void {
+    if (next === fraction) return;
+    fraction = next;
+    onfractionchange?.(next);
+  }
+
+  function release(): void {
+    dragging = false;
+  }
+
+  function key(event: KeyboardEvent): void {
+    const next = fractionForKey(event.key, position, orientation, bounds);
+    // Every other key — the other axis included — belongs to the page.
+    if (next === null) return;
+    event.preventDefault();
+    commit(next);
+  }
+</script>
+
+<div
+  bind:this={container}
+  {...rest}
+  class={slots.root({ class: className })}
+  data-orientation={orientation}
+  onpointermove={move}
+  onpointerup={release}
+  onpointercancel={release}
+>
+  <div class={slots.pane()} style="flex-basis: {percentOf(position)}">
+    {@render start?.()}
+  </div>
+
+  <!-- A focusable separator is the ARIA window splitter: interactive by role,
+       which is why it takes a tab stop and its own key handling. Svelte's a11y
+       pass reads `separator` as the static kind — the rule between two blocks
+       of text — and warns; the value bounds above are what tell it apart, and
+       are also what a screen reader announces when it lands here. -->
+  <!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+  <!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+  <div
+    class={slots.divider()}
+    data-split-view-divider
+    role="separator"
+    tabindex="0"
+    aria-label={label}
+    aria-orientation={separatorOrientation(orientation)}
+    aria-valuenow={Math.round(position * 100)}
+    aria-valuemin={Math.round(clampFraction(min, bounds) * 100)}
+    aria-valuemax={Math.round(clampFraction(max, bounds) * 100)}
+    onpointerdown={grab}
+    onlostpointercapture={release}
+    onkeydown={key}
+  ></div>
+
+  <div class={slots.pane()} style="flex-basis: {percentOf(1 - position)}">
+    {@render end?.()}
+  </div>
+</div>

package/vendor/ds/kits/app/src/primitives/list-row.variants.ts

@@ -0,0 +1,82 @@
+// ListRow's styling. See button.variants.ts for the split, the colour rule and
+// the spatial rule.
+//
+// Slots, because a row is a rail: a leading affordance, a two-line text block
+// that must truncate rather than wrap, and a trailing rail pushed to the end.
+// Those four have to agree about height and gap, so one `size` moves them
+// together.
+//
+// `interactive` is not a caller's choice — the component sets it from whether
+// the row actually does anything (see ListRow.svelte). A row that looks
+// pressable and is not is the lie this axis exists to prevent, so it cannot be
+// set independently of the element that carries the behavior.
+
+import { tv, type VariantProps } from "tailwind-variants";
+
+// The row's `size` picks WHICH spatial role each slot wears, and the
+// document's Density stop decides what those roles resolve to. The prop used
+// to be called `density`, reusing two Density stop names for a per-component
+// choice; ADR 0026 keeps Density words for the axis alone, so the scale is
+// `size` (`md`, formerly `comfortable`; `sm`, formerly `compact`). A small row
+// inside a spacious page is therefore a small row, laid out spaciously — which
+// is the arrangement a dense table inside a marketing page actually wants
+// (ADR 0003).
+const SIZE = {
+  /** The default: a row you can hit with a thumb. */
+  md: {
+    root: "gap-[var(--reddb-spatial-gap-lg)] px-[var(--reddb-spatial-inset-md)] py-[var(--reddb-spatial-inset-sm)]",
+  },
+  /** For long lists where the scan matters more than the target. */
+  sm: {
+    root: "min-h-[var(--reddb-spatial-control-height-md)] gap-[var(--reddb-spatial-gap-md)] px-[var(--reddb-spatial-inset-sm)] py-[var(--reddb-spatial-gap-md)]",
+  },
+} as const;
+
+/**
+ * The `density` values kept for one release (ADR 0026), and the `size` each
+ * one now is.
+ */
+export const DEPRECATED_LIST_ROW_DENSITIES = {
+  comfortable: "md",
+  compact: "sm",
+} as const satisfies Record<string, keyof typeof SIZE>;
+
+const INTERACTIVE = {
+  true: {
+    // Hover, pressed, focus and disabled are the quiet-control contract the
+    // component wraps an interactive row in (wave 6A).
+    root: "cursor-pointer",
+  },
+  false: { root: "" },
+} as const;
+
+const SELECTED = {
+  /** The row this list is currently about. */
+  true: { root: "bg-foreground/10", title: "font-medium text-foreground" },
+  false: { root: "" },
+} as const;
+
+export const listRow = tv({
+  slots: {
+    // `text-start` rather than the browser's default, because this same row is
+    // sometimes a <button>, which centres its text.
+    root: "flex w-full items-center border-b border-muted text-start",
+    leading: "flex shrink-0 items-center",
+    text: "flex min-w-0 flex-col gap-0.5",
+    title: "truncate text-sm font-medium text-foreground",
+    description: "truncate text-xs text-ink-muted",
+    trailing: "ms-auto flex shrink-0 items-center gap-[var(--reddb-spatial-gap-md)]",
+  },
+  variants: { size: SIZE, interactive: INTERACTIVE, selected: SELECTED },
+  defaultVariants: { size: "md", interactive: false, selected: false },
+});
+
+export type ListRowVariants = VariantProps<typeof listRow>;
+export type ListRowSize = NonNullable<ListRowVariants["size"]>;
+
+export const LIST_ROW_SIZES = Object.keys(SIZE) as readonly ListRowSize[];
+
+/** @deprecated ListRow's scale is `size` (ADR 0026); use `ListRowSize`. Removed next release. */
+export type ListRowDensity = keyof typeof DEPRECATED_LIST_ROW_DENSITIES;
+/** @deprecated ListRow's scale is `size` (ADR 0026); use `LIST_ROW_SIZES`. Removed next release. */
+export const LIST_ROW_DENSITIES = Object.keys(DEPRECATED_LIST_ROW_DENSITIES) as readonly ListRowDensity[];

package/vendor/ds/kits/app/src/primitives/nav-item.variants.ts

@@ -0,0 +1,56 @@
+// NavItem's styling. See button.variants.ts for the split, the colour rule and
+// the spatial rule.
+//
+// The active state wears the shared selection language (DESIGN.md,
+// "Interactive states"): a neutral surface, full-weight foreground ink, and a
+// 2px ink bar on the start edge. Ink, not the Brand red (wave 6A): the red bar
+// on the selected surface measured 2.49-3.01:1 on the light grounds, under
+// WCAG 1.4.11's 3:1, so the whole selection language moved to ink. Its width
+// is a plain border width, like every other rule the Kits draw. Every item
+// carries the same edge, transparent until it is current, so moving the
+// current page shifts nothing.
+//
+// A horizontal rail of items (BottomNavigation) moves the bar to the edge it
+// sits against through its own slot class.
+//
+// Opacity is doing the work an extra surface token would otherwise do, which
+// is the same choice button.variants.ts made and for the same reason: the
+// Tokens Layer ships no second surface yet.
+
+import { tv, type VariantProps } from "tailwind-variants";
+
+// Current-ness is `current` on an item (ADR 0026), as on the Base Navbar's
+// links; `active` is its one-release alias, in the recipe as on the component.
+const CURRENT = {
+  /** Where you are. */
+  true: { root: "border-foreground bg-foreground/10 font-medium text-foreground" },
+  /** Everywhere else you could go. */
+  // Rest, hover, pressed and focus come from the quiet-control contract the
+  // component wraps this slot in (wave 6A).
+  false: { root: "border-transparent bg-transparent text-ink-muted" },
+} as const;
+
+const DISABLED = {
+  /** Present, visibly unavailable, and unreachable by pointer or by tab. */
+  true: { root: "pointer-events-none opacity-50" },
+  false: { root: "" },
+} as const;
+
+export const navItem = tv({
+  slots: {
+    // Focus is the ink focus outline every DS control draws (ADR 0023).
+    root: "inline-flex w-full items-center gap-[var(--reddb-spatial-gap-md)] rounded-s-none rounded-e-md border-s-2 min-h-[var(--reddb-spatial-control-height-md)] px-[var(--reddb-spatial-inset-sm)] text-sm leading-tight focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-focus",
+    icon: "order-first shrink-0",
+    label: "truncate",
+    trailing: "ms-auto shrink-0",
+  },
+  variants: {
+    current: CURRENT,
+    /** @deprecated Renamed `current` (ADR 0026); removed next release. */
+    active: { true: CURRENT.true, false: {} },
+    disabled: DISABLED,
+  },
+  defaultVariants: { current: false, disabled: false },
+});
+
+export type NavItemVariants = VariantProps<typeof navItem>;

package/vendor/ds/kits/app/src/primitives/node-badge.variants.ts

@@ -0,0 +1,73 @@
+// NodeBadge's styling. See button.variants.ts for the split, the colour rule
+// and the spatial rule — under which the dot keeps its own size, because it is
+// a mark read at a glance rather than a space between things.
+//
+// A node's reachability is a domain reading, not a tone: the word the cluster
+// reports (`online`, `degraded`, `offline`, `unknown`) is what the badge says,
+// and it is always in the DOM (see NodeBadge.svelte). Its colour, though,
+// speaks the one semantic vocabulary (ADR 0026) through a documented mapping,
+// `NODE_STATUS_TONES`, so a degraded node reads as the same warning a Badge,
+// an Alert or a StatusIndicator draws — and never as the Brand red, which on a
+// status means danger (ADR 0023). Fill is a second cue: a node with no reading
+// gets a hollow dot, every reading a filled one.
+//
+// The marks are StatusIndicator's (each holds 3:1 on every ground, WCAG
+// 1.4.11): the role's text-grade stop ringed by its edge stop, and neutral in
+// the control edge around secondary ink.
+
+import type { Tone } from "@reddb-io/design-system/base/recipes";
+import { tv, type VariantProps } from "tailwind-variants";
+
+/** What each reachability reading means, as a tone (ADR 0026). */
+export const NODE_STATUS_TONES = {
+  /** Reachable, and keeping up. */
+  online: "success",
+  /** Reachable, and behind — lagging, rebalancing, or under pressure. */
+  degraded: "warning",
+  /** Known to the cluster, and not answering. */
+  offline: "danger",
+  /** The default: no reading yet. */
+  unknown: "neutral",
+} as const satisfies Record<string, Tone>;
+
+const MARK = {
+  neutral: "border-control-edge bg-ink-muted",
+  info: "border-[var(--reddb-color-feedback-info-border)] bg-[var(--reddb-color-feedback-info-foreground)]",
+  success:
+    "border-[var(--reddb-color-feedback-success-border)] bg-[var(--reddb-color-feedback-success-foreground)]",
+  warning:
+    "border-[var(--reddb-color-feedback-warning-border)] bg-[var(--reddb-color-feedback-warning-foreground)]",
+  danger:
+    "border-[var(--reddb-color-feedback-danger-border)] bg-[var(--reddb-color-feedback-danger-foreground)]",
+} as const satisfies Record<Tone, string>;
+
+const STATUS = {
+  online: { dot: MARK[NODE_STATUS_TONES.online] },
+  degraded: { dot: MARK[NODE_STATUS_TONES.degraded] },
+  offline: { dot: MARK[NODE_STATUS_TONES.offline] },
+  // Hollow: no reading is drawn as an empty mark, not a grey fill.
+  unknown: { dot: "border-control-edge bg-transparent" },
+} as const satisfies Record<keyof typeof NODE_STATUS_TONES, { dot: string }>;
+
+const LABELLED = {
+  /** The default: the status word is drawn next to the node's name. */
+  true: { status: "text-ink-muted" },
+  /** Announced, never drawn — for a dense cluster list. */
+  false: { status: "sr-only" },
+} as const;
+
+export const nodeBadge = tv({
+  slots: {
+    root: "inline-flex items-center gap-[var(--reddb-spatial-gap-md)] rounded-full border border-muted px-2.5 py-1 text-xs leading-tight whitespace-nowrap",
+    dot: "size-2 shrink-0 rounded-full border",
+    name: "font-mono text-foreground",
+    status: "",
+  },
+  variants: { status: STATUS, labelled: LABELLED },
+  defaultVariants: { status: "unknown", labelled: true },
+});
+
+export type NodeBadgeVariants = VariantProps<typeof nodeBadge>;
+export type NodeStatus = NonNullable<NodeBadgeVariants["status"]>;
+
+export const NODE_STATUSES = Object.keys(STATUS) as readonly NodeStatus[];

package/vendor/ds/kits/app/src/primitives/pill.variants.ts

@@ -0,0 +1,117 @@
+// Pill's styling. See button.variants.ts for the split, the colour rule and the
+// spatial rule — under which only the medium size's inset lands on a role the
+// axis ships. The small size is a notch below the narrowest one, and a value
+// the axis has no role for stays a step rather than being pushed onto the
+// nearest, which would move what the neutral stop renders.
+//
+// A Pill is round-ended (`rounded-full`) and stands on its own: a filter that
+// is on, a tag, a selected facet. That is why it — unlike Badge — has a size
+// axis and a dismissible affordance.
+//
+// What a Pill means is `tone`, the one semantic vocabulary (ADR 0026), and how
+// strongly it is drawn is `variant`, its emphasis axis — the same two axes, and
+// the same pairs, as the Base Badge, so a `tone="warning"` Pill and a
+// `tone="warning"` Badge are one Feedback Role. No tone fills with the Brand
+// red: red on a status is danger (ADR 0023).
+
+import { TONES, type Tone } from "@reddb-io/design-system/base/recipes";
+import { tv, type VariantProps } from "tailwind-variants";
+
+/** How strongly a Pill's tone is drawn — its emphasis axis. */
+export const PILL_VARIANTS = ["tinted", "filled", "outline"] as const;
+export type PillVariant = (typeof PILL_VARIANTS)[number];
+
+/** The tones a Pill accepts: the shared vocabulary (ADR 0026). */
+export const PILL_TONES = TONES;
+export type PillTone = Tone;
+
+/**
+ * Variant values kept for one release (ADR 0026). `neutral` is the tinted
+ * neutral pill it always drew; `primary` keeps its accent fill and warns — a
+ * meaning is a tone (`tone="info" variant="filled"`), never the accent.
+ */
+export const DEPRECATED_PILL_VARIANTS = {
+  neutral: "tinted",
+  primary: "filled",
+} as const satisfies Record<string, PillVariant>;
+/** @deprecated `neutral` is `variant="tinted"`; `primary` is a filled tone. Removed next release. */
+export type DeprecatedPillVariant = keyof typeof DEPRECATED_PILL_VARIANTS;
+
+const APPEARANCE = {
+  tinted: {
+    neutral: "border-transparent bg-muted text-foreground",
+    info: "border-transparent bg-feedback-info-surface text-feedback-info-foreground",
+    success: "border-transparent bg-feedback-success-surface text-feedback-success-foreground",
+    warning: "border-transparent bg-feedback-warning-surface text-feedback-warning-foreground",
+    danger: "border-transparent bg-feedback-danger-surface text-feedback-danger-foreground",
+  },
+  filled: {
+    neutral: "border-transparent bg-foreground text-background",
+    info: "border-transparent bg-feedback-info-foreground text-on-feedback",
+    success: "border-transparent bg-feedback-success-foreground text-on-feedback",
+    warning: "border-transparent bg-feedback-warning-foreground text-on-feedback",
+    danger: "border-transparent bg-feedback-danger-foreground text-on-feedback",
+  },
+  outline: {
+    neutral: "border-muted bg-transparent text-foreground",
+    info: "border-feedback-info-border bg-transparent text-feedback-info-foreground",
+    success: "border-feedback-success-border bg-transparent text-feedback-success-foreground",
+    warning: "border-feedback-warning-border bg-transparent text-feedback-warning-foreground",
+    danger: "border-feedback-danger-border bg-transparent text-feedback-danger-foreground",
+  },
+} as const satisfies Record<PillVariant, Record<Tone, string>>;
+
+/** The accent fill the deprecated `variant="primary"` still draws for one release. */
+const DEPRECATED_PRIMARY = "border-transparent bg-primary text-on-primary";
+
+const TONE = { neutral: "", info: "", success: "", warning: "", danger: "" } as const satisfies Record<
+  Tone,
+  string
+>;
+const VARIANT = { tinted: "", filled: "", outline: "", neutral: "", primary: "" } as const;
+
+const SIZE = {
+  sm: "px-2.5 py-0.5 text-xs",
+  md: "px-[var(--reddb-spatial-inset-sm)] py-1 text-sm",
+} as const;
+
+export const pill = tv({
+  base: "inline-flex items-center gap-1.5 rounded-full border leading-tight whitespace-nowrap",
+  variants: { tone: TONE, variant: VARIANT, size: SIZE },
+  compoundVariants: [
+    ...(Object.entries(APPEARANCE) as [PillVariant, Record<Tone, string>][]).flatMap(([variant, tones]) =>
+      (Object.entries(tones) as [Tone, string][]).map(([tone, className]) => ({
+        variant,
+        tone,
+        class: className,
+      })),
+    ),
+    // The deprecated neutral variant is the tinted pill, tone for tone.
+    ...(Object.entries(APPEARANCE.tinted) as [Tone, string][]).map(([tone, className]) => ({
+      variant: "neutral" as const,
+      tone,
+      class: className,
+    })),
+    { variant: "primary" as const, class: DEPRECATED_PRIMARY },
+  ],
+  defaultVariants: { tone: "neutral", variant: "tinted", size: "md" },
+});
+
+/**
+ * The dismiss affordance, styled to inherit the Pill's own colour. The glyph
+ * stays small, but its hit area is a control-height-sm square centred on it,
+ * so the target never drops below 24px (WCAG 2.2 SC 2.5.8). Its rest, hover,
+ * pressed and focus states are the quiet-control contract the component wraps
+ * it in (wave 6A).
+ */
+export const pillDismiss = tv({
+  base: [
+    "relative -me-1 inline-flex items-center justify-center rounded-full border border-transparent bg-transparent p-0.5 leading-tight",
+    "before:absolute before:left-1/2 before:top-1/2 before:size-[var(--reddb-spatial-control-height-sm)] before:-translate-x-1/2 before:-translate-y-1/2 before:content-['']",
+  ].join(" "),
+});
+
+export type PillVariants = VariantProps<typeof pill>;
+export type PillSize = keyof typeof SIZE;
+
+export const PILL_SIZES = Object.keys(SIZE) as readonly PillSize[];

package/vendor/ds/kits/app/src/primitives/split-view.behavior.ts

@@ -0,0 +1,113 @@
+// SplitView's behavior, with no DOM in sight.
+//
+// Everything a resizable split does that is worth getting right is arithmetic:
+// where a pointer lands inside a box, how far an arrow key moves the divider,
+// and what stops either from collapsing a pane to nothing. Kept here, that
+// arithmetic is testable without a browser, and SplitView.svelte is left
+// holding only the parts that genuinely need one — the element, the pointer
+// capture and the keyboard listener.
+//
+// The unit throughout is a *fraction* of the container, never a pixel width: a
+// split expressed in pixels stops meaning anything the moment its container
+// resizes, and a Kit component has no idea how big its container will be in an
+// application it has never seen.
+
+/** The axis the panes are laid out along. */
+export const SPLIT_ORIENTATIONS = ["horizontal", "vertical"] as const;
+export type SplitOrientation = (typeof SPLIT_ORIENTATIONS)[number];
+
+/** How much of the container the start pane may take. */
+export interface SplitBounds {
+  /** Smallest fraction the start pane may shrink to. */
+  min: number;
+  /** Largest fraction it may grow to. */
+  max: number;
+}
+
+/**
+ * The default bounds. Neither pane can go below a tenth: a pane dragged to
+ * zero looks like a bug in the application rather than a position of the
+ * divider, and nothing in the DOM would tell a user it is still there.
+ */
+export const SPLIT_BOUNDS: SplitBounds = { min: 0.1, max: 0.9 };
+
+/** How far one arrow key press moves the divider. */
+export const SPLIT_STEP = 0.02;
+
+/** `bounds`, in the order the arithmetic needs them whichever way round they came. */
+function ordered(bounds: SplitBounds): SplitBounds {
+  return { min: Math.min(bounds.min, bounds.max), max: Math.max(bounds.min, bounds.max) };
+}
+
+/**
+ * `fraction`, held inside `bounds`.
+ *
+ * A fraction that is not a finite number is a caller's bug, and it resolves to
+ * the midpoint rather than propagating: `NaN` would reach the DOM as a style
+ * the browser drops, leaving a split that is silently unsplit.
+ */
+export function clampFraction(fraction: number, bounds: SplitBounds = SPLIT_BOUNDS): number {
+  const { min, max } = ordered(bounds);
+  if (!Number.isFinite(fraction)) return clampFraction(0.5, bounds);
+  return Math.min(max, Math.max(min, fraction));
+}
+
+/**
+ * The fraction a pointer `offset` from the container's leading edge means,
+ * given the container's `size` along the same axis.
+ *
+ * `null` when the container has no measurable size — which is what a hidden
+ * container, or one measured before layout, gives back. A drag that cannot be
+ * measured must leave the divider where it is, not slam it to an edge.
+ */
+export function fractionAt(
+  offset: number,
+  size: number,
+  bounds: SplitBounds = SPLIT_BOUNDS,
+): number | null {
+  if (!Number.isFinite(offset) || !Number.isFinite(size) || size <= 0) return null;
+  return clampFraction(offset / size, bounds);
+}
+
+/**
+ * The fraction `key` moves the divider to, or `null` when the key means
+ * nothing here.
+ *
+ * `null` is the important half: the keys of the other axis, and every key that
+ * is not a movement, have to reach the page. A separator that swallowed every
+ * arrow would take the page's scrolling with it.
+ */
+export function fractionForKey(
+  key: string,
+  fraction: number,
+  orientation: SplitOrientation,
+  bounds: SplitBounds = SPLIT_BOUNDS,
+  step: number = SPLIT_STEP,
+): number | null {
+  const current = clampFraction(fraction, bounds);
+  const { min, max } = ordered(bounds);
+
+  if (key === "Home") return min;
+  if (key === "End") return max;
+
+  const back = orientation === "horizontal" ? "ArrowLeft" : "ArrowUp";
+  const forward = orientation === "horizontal" ? "ArrowRight" : "ArrowDown";
+  if (key === back) return clampFraction(current - step, bounds);
+  if (key === forward) return clampFraction(current + step, bounds);
+
+  return null;
+}
+
+/** `0.425` -> `"42.5%"`, at a tenth of a percent — enough for a pixel either way. */
+export function percentOf(fraction: number): string {
+  return `${Math.round(clampFraction(fraction, { min: 0, max: 1 }) * 1000) / 10}%`;
+}
+
+/**
+ * The separator's own orientation, which is the opposite of the split's: panes
+ * side by side are divided by a vertical rule. ARIA names the separator, not
+ * the layout, so this is a translation and not a synonym.
+ */
+export function separatorOrientation(orientation: SplitOrientation): SplitOrientation {
+  return orientation === "horizontal" ? "vertical" : "horizontal";
+}