@lyeve-labs/ui-kit 0.12.1 → 0.13.1

package/dist/components/TreeView.svelte

@@ -0,0 +1,339 @@
+<script lang="ts" generics="T = unknown">
+  import { ChevronRight } from '@lucide/svelte';
+  import { CHOICE_MARK, choiceBox } from '../internal/choice.js';
+  import {
+    branchState,
+    flattenTree,
+    isBranch,
+    toggleSubtree,
+    type TreeNode,
+    type TriState,
+  } from '../internal/tree.js';
+
+  interface Props {
+    nodes: TreeNode<T>[];
+    /** Required. An unnamed tree announces as just "tree". */
+    label: string;
+    expanded?: string[];
+    selected?: string;
+    /** Checked LEAF ids only. A branch's state is always derived, never stored, so the two cannot disagree. */
+    checked?: string[];
+    checkable?: boolean;
+    class?: string;
+    onactivate?: (node: TreeNode<T>) => void;
+    oncheck?: (checked: string[]) => void;
+  }
+
+  let {
+    nodes,
+    label,
+    expanded = $bindable([]),
+    selected = $bindable(undefined),
+    checked = $bindable([]),
+    checkable = false,
+    class: klass = '',
+    onactivate,
+    oncheck,
+  }: Props = $props();
+
+  let rootEl: HTMLUListElement | undefined = $state();
+
+  /** The row the roving tabindex sits on. Undefined until the user lands somewhere. */
+  let activeId: string | undefined = $state(undefined);
+
+  const expandedSet = $derived(new Set(expanded));
+  const checkedSet = $derived(new Set(checked));
+
+  /**
+   * The visible rows, which is both the paint order and the arrow-key order.
+   * A collapsed branch contributes no children here, so ArrowDown cannot land
+   * on a row the user cannot see.
+   */
+  const rows = $derived(flattenTree(nodes, expandedSet));
+
+  /**
+   * Exactly one row is in the tab sequence, and the arrows move it.
+   *
+   * A tree is one stop, not one stop per row: a hundred-node tree with a
+   * tabbable row each is a hundred presses to get past. The fallback chain
+   * matters as much as the rule. The active row can be gone after a collapse
+   * or a data change, so the tabbable row falls back to the selected row and
+   * then to the first, and a tree with no row the keyboard can reach is a tree
+   * nobody can enter.
+   */
+  const tabbableId = $derived(
+    rows.find((r) => r.node.id === activeId)?.node.id ??
+      rows.find((r) => r.node.id === selected)?.node.id ??
+      rows[0]?.node.id,
+  );
+
+  /** Typeahead buffer. Not state: nothing renders it, and it clears on a timer. */
+  let typed = '';
+  let typedTimer: ReturnType<typeof setTimeout> | undefined;
+
+  $effect(() => () => clearTimeout(typedTimer));
+
+  function ariaChecked(state: TriState): 'true' | 'false' | 'mixed' {
+    if (state === 'all') return 'true';
+    return state === 'some' ? 'mixed' : 'false';
+  }
+
+  function rowPaint(isSelected: boolean, disabled: boolean): string {
+    // One utility per property in each branch. A resting `hover:bg-surface-2`
+    // that a selected row overrides with `bg-surface-2` resolves by the order
+    // Tailwind emits the two, not by the order they are written here.
+    if (disabled) return 'cursor-not-allowed opacity-50';
+    return isSelected
+      ? 'cursor-pointer bg-surface-2 font-medium text-brand'
+      : 'cursor-pointer hover:bg-surface-2';
+  }
+
+  function rowElement(id: string): HTMLElement | undefined {
+    if (!rootEl) return undefined;
+    return [...rootEl.querySelectorAll<HTMLElement>('[role="treeitem"]')].find(
+      (el) => el.dataset.treeId === id,
+    );
+  }
+
+  function focusRow(id: string | undefined): void {
+    if (id === undefined) return;
+    activeId = id;
+    rowElement(id)?.focus();
+  }
+
+  function setOpen(node: TreeNode<T>, open: boolean): void {
+    if (!isBranch(node)) return;
+    const next = new Set(expanded);
+    if (open) next.add(node.id);
+    else next.delete(node.id);
+    expanded = [...next];
+  }
+
+  function toggleOpen(node: TreeNode<T>): void {
+    setOpen(node, !expandedSet.has(node.id));
+  }
+
+  function activate(node: TreeNode<T>): void {
+    if (node.disabled) return;
+    selected = node.id;
+    onactivate?.(node);
+  }
+
+  function toggleCheck(node: TreeNode<T>): void {
+    if (!checkable || node.disabled) return;
+    const next = new Set(checked);
+    const { add, remove } = toggleSubtree(node, next);
+    // A branch with no enabled leaf has nothing to write, and reporting a
+    // change that did not happen is how a consumer ends up saving a list it was
+    // never given.
+    if (add.length === 0 && remove.length === 0) return;
+    for (const id of add) next.add(id);
+    for (const id of remove) next.delete(id);
+    checked = [...next];
+    oncheck?.(checked);
+  }
+
+  function typeahead(key: string, fromId: string): void {
+    clearTimeout(typedTimer);
+    typedTimer = setTimeout(() => {
+      typed = '';
+    }, 500);
+    typed += key.toLowerCase();
+
+    const start = rows.findIndex((r) => r.node.id === fromId);
+    // A single character looks past the current row, so pressing it again walks
+    // the matches. A longer buffer includes the current row, or refining a
+    // search on the row it already found would jump off it.
+    const from = typed.length === 1 ? start + 1 : start;
+    for (let step = 0; step < rows.length; step++) {
+      const candidate = rows[(from + step + rows.length) % rows.length];
+      if (candidate.node.label.toLowerCase().startsWith(typed)) {
+        focusRow(candidate.node.id);
+        return;
+      }
+    }
+  }
+
+  function onRowClick(e: MouseEvent, node: TreeNode<T>): void {
+    const target = e.target as Element | null;
+    // Every row is nested inside its ancestors, so a click on a child bubbles
+    // through all of them. A row answers only for a target that is its own.
+    if (!target || target.closest('[role="treeitem"]') !== e.currentTarget) return;
+
+    activeId = node.id;
+    if (target.closest('[data-tree-toggle]')) {
+      toggleOpen(node);
+      return;
+    }
+    if (checkable && target.closest('[data-tree-check]')) {
+      toggleCheck(node);
+      return;
+    }
+    // A branch that does not open when its row is clicked reads as broken, so
+    // the row body opens it as well as activating it.
+    if (isBranch(node)) toggleOpen(node);
+    activate(node);
+  }
+
+  function onRowKeydown(e: KeyboardEvent, node: TreeNode<T>, parentId: string | undefined): void {
+    // Keydown bubbles the same way a click does, and only the focused row is
+    // the target.
+    if (e.target !== e.currentTarget) return;
+
+    const index = rows.findIndex((r) => r.node.id === node.id);
+    const open = expandedSet.has(node.id);
+
+    switch (e.key) {
+      case 'ArrowDown':
+        e.preventDefault();
+        focusRow(rows[index + 1]?.node.id);
+        return;
+      case 'ArrowUp':
+        e.preventDefault();
+        focusRow(rows[index - 1]?.node.id);
+        return;
+      case 'Home':
+        e.preventDefault();
+        focusRow(rows[0]?.node.id);
+        return;
+      case 'End':
+        e.preventDefault();
+        focusRow(rows[rows.length - 1]?.node.id);
+        return;
+      case 'ArrowRight':
+        e.preventDefault();
+        // Opening and descending are two presses. The first press has to leave
+        // focus where it is, or a screen reader announces the child before its
+        // parent has said it is now open.
+        if (!isBranch(node)) return;
+        if (!open) setOpen(node, true);
+        else focusRow(node.children?.[0]?.id);
+        return;
+      case 'ArrowLeft':
+        e.preventDefault();
+        if (isBranch(node) && open) setOpen(node, false);
+        else focusRow(parentId);
+        return;
+      case 'Enter':
+        e.preventDefault();
+        activate(node);
+        return;
+      case ' ':
+        // Space never reaches the typeahead below. One key that both toggles a
+        // check and activates a row leaves the user unable to do either on
+        // purpose, so a checkable tree gives Space to the check and keeps
+        // Enter for activation.
+        e.preventDefault();
+        if (checkable) toggleCheck(node);
+        else activate(node);
+        return;
+      default:
+        if (e.key.length === 1 && !e.ctrlKey && !e.metaKey && !e.altKey) {
+          e.preventDefault();
+          typeahead(e.key, node.id);
+        }
+    }
+  }
+</script>
+
+{#snippet branch(list: TreeNode<T>[], depth: number, parentId: string | undefined)}
+  {#each list as node, i (node.id)}
+    {@const open = expandedSet.has(node.id)}
+    {@const state = branchState(node, checkedSet)}
+    <!--
+      The focus ring is stated once, on the element that holds the role and the
+      focus, and outside every selected and checked branch. A ring inside the
+      selected ternary disappears in the state it was meant to mark, and a
+      selected row already carries a brand text colour that a border-only focus
+      state would have nothing to add to. Inset, because a tree of any size
+      lives in a scrolling container that would crop an outset ring.
+    -->
+    <li
+      role="treeitem"
+      data-tree-id={node.id}
+      tabindex={node.id === tabbableId ? 0 : -1}
+      aria-level={depth + 1}
+      aria-setsize={list.length}
+      aria-posinset={i + 1}
+      aria-expanded={isBranch(node) ? open : undefined}
+      aria-selected={selected === node.id}
+      aria-checked={checkable ? ariaChecked(state) : undefined}
+      aria-disabled={node.disabled ? 'true' : undefined}
+      class="rounded-md outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-brand"
+      onclick={(e) => onRowClick(e, node)}
+      onkeydown={(e) => onRowKeydown(e, node, parentId)}
+      onfocus={() => (activeId = node.id)}
+    >
+      <!--
+        Indentation is a style attribute reading the spacing tokens. A class
+        built by interpolating the depth matches no candidate in Tailwind's
+        scan, so no rule is generated and every row draws flush left.
+      -->
+      <div
+        class="flex w-full items-center gap-2 rounded-md py-1.5 pr-2 text-sm transition-colors duration-150 {rowPaint(
+          selected === node.id,
+          !!node.disabled,
+        )}"
+        style="padding-left: calc(var(--spacing-inline) + {depth} * var(--spacing-stack))"
+      >
+        {#if isBranch(node)}
+          <span
+            data-tree-toggle
+            class="flex h-4 w-4 shrink-0 items-center justify-center text-faint"
+          >
+            <ChevronRight
+              size={14}
+              class="transition-transform duration-150 {open ? 'rotate-90' : ''}"
+            />
+          </span>
+        {:else}
+          <span class="h-4 w-4 shrink-0"></span>
+        {/if}
+
+        {#if checkable}
+          <!--
+            A painted box rather than an input: the treeitem itself carries
+            aria-checked, and a focusable control inside the row would put a
+            second tab stop in a widget whose whole point is that it has one.
+          -->
+          <span data-tree-check class="flex shrink-0 items-center">
+            <span class={choiceBox('checkbox', 'sm', state === 'all', state === 'some')}>
+              {#if state !== 'none'}
+                <svg width="10" height="8" viewBox="0 0 10 8" fill="none" aria-hidden="true">
+                  <path
+                    d={state === 'all' ? CHOICE_MARK.check : CHOICE_MARK.mixed}
+                    stroke="currentColor"
+                    stroke-width="1.5"
+                    stroke-linecap="round"
+                    stroke-linejoin="round"
+                  />
+                </svg>
+              {/if}
+            </span>
+          </span>
+        {/if}
+
+        {#if node.icon}
+          {@const Icon = node.icon}
+          <Icon size={14} class="shrink-0 text-faint" />
+        {/if}
+
+        <span class="truncate">{node.label}</span>
+
+        {#if node.badge !== undefined}
+          <span class="ml-auto shrink-0 pl-2 text-xs text-faint">{node.badge}</span>
+        {/if}
+      </div>
+
+      {#if isBranch(node) && open}
+        <ul role="group">
+          {@render branch(node.children ?? [], depth + 1, node.id)}
+        </ul>
+      {/if}
+    </li>
+  {/each}
+{/snippet}
+
+<ul bind:this={rootEl} role="tree" aria-label={label} class="text-fg select-none {klass}">
+  {@render branch(nodes, 0, undefined)}
+</ul>

package/dist/components/TreeView.svelte.d.ts

@@ -0,0 +1,37 @@
+import { type TreeNode } from '../internal/tree.js';
+declare function $$render<T = unknown>(): {
+    props: {
+        nodes: TreeNode<T>[];
+        /** Required. An unnamed tree announces as just "tree". */
+        label: string;
+        expanded?: string[];
+        selected?: string;
+        /** Checked LEAF ids only. A branch's state is always derived, never stored, so the two cannot disagree. */
+        checked?: string[];
+        checkable?: boolean;
+        class?: string;
+        onactivate?: (node: TreeNode<T>) => void;
+        oncheck?: (checked: string[]) => void;
+    };
+    exports: {};
+    bindings: "expanded" | "selected" | "checked";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T = unknown> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "expanded" | "selected" | "checked";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T = unknown>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T = unknown>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const TreeView: $$IsomorphicComponent;
+type TreeView<T = unknown> = InstanceType<typeof TreeView<T>>;
+export default TreeView;

package/dist/index.d.ts

@@ -7,32 +7,55 @@
  * is an implementation detail.
  */
 export { default as Card } from './components/Card.svelte';
+export { default as Panel } from './components/Panel.svelte';
+export { default as PageShell } from './components/PageShell.svelte';
 export { default as PageHeader } from './components/PageHeader.svelte';
+export { default as SectionHeading } from './components/SectionHeading.svelte';
 export { default as Divider } from './components/Divider.svelte';
 export { default as Accordion } from './components/Accordion.svelte';
 export { default as AccordionItem } from './components/AccordionItem.svelte';
+export { default as Collapsible } from './components/Collapsible.svelte';
 export { default as Table } from './components/Table.svelte';
+export { default as DescriptionList } from './components/DescriptionList.svelte';
+export { default as Toolbar } from './components/Toolbar.svelte';
+export { default as TreeView } from './components/TreeView.svelte';
+export type { PageWidth } from './internal/layout.js';
+export type { TreeNode, TriState } from './internal/tree.js';
 export { default as Button } from './components/Button.svelte';
 export { default as ButtonGroup } from './components/ButtonGroup.svelte';
 export { default as Input } from './components/Input.svelte';
+export { default as PasswordInput } from './components/PasswordInput.svelte';
 export { default as Textarea } from './components/Textarea.svelte';
 export { default as NumberInput } from './components/NumberInput.svelte';
 export { default as SearchInput } from './components/SearchInput.svelte';
 export { default as FileInput } from './components/FileInput.svelte';
 export { default as Label } from './components/Label.svelte';
+export { default as Field } from './components/Field.svelte';
+export { default as FormMessage } from './components/FormMessage.svelte';
+export { default as SegmentedControl } from './components/SegmentedControl.svelte';
 export { default as Select } from './components/Select.svelte';
 export { default as MultiSelect } from './components/MultiSelect.svelte';
 export { default as Autocomplete } from './components/Autocomplete.svelte';
 export { default as DatePicker } from './components/DatePicker.svelte';
+export { default as TimePicker } from './components/TimePicker.svelte';
+export { default as DateTimePicker } from './components/DateTimePicker.svelte';
 export { default as Checkbox } from './components/Checkbox.svelte';
+export { default as CheckboxGroup } from './components/CheckboxGroup.svelte';
 export { default as Radio } from './components/Radio.svelte';
 export { default as RadioGroup } from './components/RadioGroup.svelte';
 export { default as Toggle } from './components/Toggle.svelte';
+export type { ChoiceSize, ChoiceVariant, ChoiceOrientation } from './internal/choice.js';
+export type { ChoiceOption } from './components/CheckboxGroup.svelte';
+export type { SelectOption, SelectChangeEvent } from './components/Select.svelte';
+export type { ListOption } from './components/Autocomplete.svelte';
+export type { FilterFn, FilterInput, FilterContext } from './internal/filter.js';
 export { default as Breadcrumb } from './components/Breadcrumb.svelte';
 export { default as Tabs } from './components/Tabs.svelte';
 export { default as Pagination } from './components/Pagination.svelte';
 export { default as StepIndicator } from './components/StepIndicator.svelte';
 export { default as Dropdown } from './components/Dropdown.svelte';
+export { default as SidebarNav } from './components/SidebarNav.svelte';
+export type { NavNode, NavTree } from './internal/nav-tree.js';
 export { default as Modal } from './components/Modal.svelte';
 export { default as Drawer } from './components/Drawer.svelte';
 export { default as Tooltip } from './components/Tooltip.svelte';
@@ -47,6 +70,7 @@ export { default as Skeleton } from './components/Skeleton.svelte';
 export { default as EmptyState } from './components/EmptyState.svelte';
 export { default as Stat } from './components/Stat.svelte';
 export { default as Kbd } from './components/Kbd.svelte';
+export { default as CopyButton } from './components/CopyButton.svelte';
 export { default as Avatar } from './components/Avatar.svelte';
 export { default as AvatarGroup } from './components/AvatarGroup.svelte';
 export { default as ThemeToggle } from './components/ThemeToggle.svelte';
@@ -60,4 +84,4 @@ export { openDialog, closeDialog, dismissDialog, dismissAllDialogs, confirm, set
 export type { DialogOptions, DialogEntry, DialogSize } from './components/dialog/types.js';
 export { cn, type ClassValue } from './utils/cn.js';
 export { getTheme, setTheme, toggleTheme, themeBootScript, type Theme } from './utils/theme.js';
-export declare const VERSION = "0.12.1";
+export declare const VERSION = "0.13.1";

package/dist/index.js

@@ -8,25 +8,42 @@
  */
 // ── Layout & structure ─────────────────────────────────────────────────────
 export { default as Card } from './components/Card.svelte';
+export { default as Panel } from './components/Panel.svelte';
+export { default as PageShell } from './components/PageShell.svelte';
 export { default as PageHeader } from './components/PageHeader.svelte';
+export { default as SectionHeading } from './components/SectionHeading.svelte';
 export { default as Divider } from './components/Divider.svelte';
 export { default as Accordion } from './components/Accordion.svelte';
 export { default as AccordionItem } from './components/AccordionItem.svelte';
+export { default as Collapsible } from './components/Collapsible.svelte';
 export { default as Table } from './components/Table.svelte';
+export { default as DescriptionList } from './components/DescriptionList.svelte';
+export { default as Toolbar } from './components/Toolbar.svelte';
+export { default as TreeView } from './components/TreeView.svelte';
 // ── Forms & inputs ─────────────────────────────────────────────────────────
 export { default as Button } from './components/Button.svelte';
 export { default as ButtonGroup } from './components/ButtonGroup.svelte';
 export { default as Input } from './components/Input.svelte';
+export { default as PasswordInput } from './components/PasswordInput.svelte';
 export { default as Textarea } from './components/Textarea.svelte';
 export { default as NumberInput } from './components/NumberInput.svelte';
 export { default as SearchInput } from './components/SearchInput.svelte';
 export { default as FileInput } from './components/FileInput.svelte';
 export { default as Label } from './components/Label.svelte';
+// The field furniture as a component, for a consumer composing a control the
+// kit does not ship. internal/field.ts stays private, and a page that could
+// not reach it hand-copied the class strings instead.
+export { default as Field } from './components/Field.svelte';
+export { default as FormMessage } from './components/FormMessage.svelte';
+export { default as SegmentedControl } from './components/SegmentedControl.svelte';
 export { default as Select } from './components/Select.svelte';
 export { default as MultiSelect } from './components/MultiSelect.svelte';
 export { default as Autocomplete } from './components/Autocomplete.svelte';
 export { default as DatePicker } from './components/DatePicker.svelte';
+export { default as TimePicker } from './components/TimePicker.svelte';
+export { default as DateTimePicker } from './components/DateTimePicker.svelte';
 export { default as Checkbox } from './components/Checkbox.svelte';
+export { default as CheckboxGroup } from './components/CheckboxGroup.svelte';
 export { default as Radio } from './components/Radio.svelte';
 export { default as RadioGroup } from './components/RadioGroup.svelte';
 export { default as Toggle } from './components/Toggle.svelte';
@@ -36,6 +53,7 @@ export { default as Tabs } from './components/Tabs.svelte';
 export { default as Pagination } from './components/Pagination.svelte';
 export { default as StepIndicator } from './components/StepIndicator.svelte';
 export { default as Dropdown } from './components/Dropdown.svelte';
+export { default as SidebarNav } from './components/SidebarNav.svelte';
 // ── Overlays ───────────────────────────────────────────────────────────────
 export { default as Modal } from './components/Modal.svelte';
 export { default as Drawer } from './components/Drawer.svelte';
@@ -52,6 +70,7 @@ export { default as Skeleton } from './components/Skeleton.svelte';
 export { default as EmptyState } from './components/EmptyState.svelte';
 export { default as Stat } from './components/Stat.svelte';
 export { default as Kbd } from './components/Kbd.svelte';
+export { default as CopyButton } from './components/CopyButton.svelte';
 // ── Media ──────────────────────────────────────────────────────────────────
 export { default as Avatar } from './components/Avatar.svelte';
 export { default as AvatarGroup } from './components/AvatarGroup.svelte';
@@ -71,4 +90,4 @@ export { getTheme, setTheme, toggleTheme, themeBootScript } from './utils/theme.
 // ── Version ────────────────────────────────────────────────────────────────
 // Generated from package.json by `pnpm version:sync`. Bump package.json, never
 // this line; the build and the test suite fail when the two disagree.
-export const VERSION = '0.12.1';
+export const VERSION = '0.13.1';

package/dist/internal/calendar.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Month arithmetic for the date controls, done without the Date parser.
+ *
+ * The rule this module exists to enforce: no string is ever handed to the Date
+ * parser. `new Date('2026-01-02')` is UTC midnight by specification and
+ * `new Date('2026-01-02T00:00')` is local midnight, so one helper applied to a
+ * date field and to a datetime field lands in two different zones. Read the
+ * first form back through the local getters west of UTC and it is 1 January.
+ * That is the off by one day, and it appears only for the part of the world
+ * that is not on UTC, which is why it survives a developer's own testing.
+ *
+ * DatePicker binds `value` to an ISO calendar date spelled `YYYY-MM-DD`: four
+ * digit year, two digit zero padded month, two digit zero padded day, with the
+ * empty string standing for no date. Its `min` and `max` props take the same
+ * spelling and are compared as plain strings, which works only because that
+ * spelling sorts lexicographically. DateRangePicker and DateTimePicker will
+ * carry the same value and need the same arithmetic, and each of the three is a
+ * place the zone bug enters, so the arithmetic is stated once here.
+ *
+ * The numeric Date constructor is avoided as well. `new Date(24, 0, 1)` is
+ * 1924, because the constructor remaps years 0 through 99 into the twentieth
+ * century, and the year in a date field comes from a user. Everything below is
+ * integer arithmetic on the proleptic Gregorian calendar. The one Date in the
+ * file is the no argument one inside todayLocal, which is the only place a real
+ * clock is needed.
+ *
+ * Not exported from the package entry point - this is an implementation detail.
+ */
+/** A calendar date with no zone and no time. m is 1-12, the month a human says, not the 0-11 the Date constructor takes. */
+export interface CalendarDate {
+    y: number;
+    m: number;
+    d: number;
+}
+/**
+ * Reads the `YYYY-MM-DD` DatePicker binds, or null when the string is not one.
+ *
+ * Shape checks and round trips. `2024-13-45` returns null rather than silently
+ * becoming the 2025-02-14 those three numbers normalize to in a Date: a picker
+ * that accepted it would open on a month the user never typed and report a
+ * value they never chose. A day is rejected when its month does not have it, so
+ * `2024-02-30` and `2023-02-29` are both null while `2024-02-29` is a date.
+ * Undefined and the empty string are null too, because an unset field is the
+ * ordinary state of a date input and not an error.
+ */
+export declare function parseISODate(s: string | undefined | null): CalendarDate | null;
+/**
+ * Writes the `YYYY-MM-DD` DatePicker binds.
+ *
+ * Every part is zero padded, including the year, because the min and max
+ * comparison in the control is a string comparison: an unpadded `2024-1-5`
+ * sorts after `2024-12-01` and the bound then rejects dates inside it.
+ */
+export declare function toISODate(date: CalendarDate): string;
+/**
+ * Today in the viewer's own zone, read from the Date's local getters and never
+ * from its ISO string.
+ *
+ * `new Date().toISOString().slice(0, 10)` is the tempting one line version and
+ * it is wrong: it converts to UTC first, so a viewer in Jakarta gets yesterday
+ * until 7am and a viewer in New York gets tomorrow from the evening on. The
+ * date the calendar marks as today has to be the date on the wall behind the
+ * viewer.
+ */
+export declare function todayLocal(): CalendarDate;
+/**
+ * Days in a month, leap years included.
+ *
+ * A month outside 1 to 12 has no days and returns 0, so a caller bounding a day
+ * against it rejects the month rather than accepting a day in a month that does
+ * not exist.
+ */
+export declare function daysInMonth(y: number, m: number): number;
+/** Weekday of the first of the month, 0 for Sunday. */
+export declare function firstWeekday(y: number, m: number): number;
+/**
+ * Adds months, clamping the day rather than rolling into the next month.
+ *
+ * 31 January plus one month is 28 or 29 February, never 2 or 3 March. A Date
+ * rolls, so paging a picker forward from the 31st and back again lands the user
+ * on a different day than the one they were looking at, and a range whose start
+ * was the 31st can end up after its own end.
+ */
+export declare function addMonths(date: CalendarDate, delta: number): CalendarDate;
+/** Adds days across month and year boundaries, leap days included. */
+export declare function addDays(date: CalendarDate, delta: number): CalendarDate;
+/**
+ * Orders two dates as -1, 0 or 1.
+ *
+ * A total order, so a caller can sort and bound without constructing a Date.
+ * Returning the field difference would sort just as well and would report 2 for
+ * two years apart, which quietly breaks the caller that tests for 1.
+ */
+export declare function compareDates(a: CalendarDate, b: CalendarDate): number;
+/**
+ * Inclusive on both ends. Either bound may be null, meaning unbounded.
+ *
+ * Inclusive because a picker given min and max for a single allowed day has to
+ * offer that day. DatePicker compares its bounds as strings today, which agrees
+ * with this only while every bound is zero padded.
+ */
+export declare function withinRange(date: CalendarDate, min: CalendarDate | null, max: CalendarDate | null): boolean;
+/**
+ * The six week grid a month renders, always 42 cells so the calendar does not
+ * change height between months. Cells outside the viewed month carry
+ * `outside: true`.
+ *
+ * DatePicker pads its lead with empty spans and stops at the last day, so
+ * February in a year where it starts on a Sunday draws four rows and a 31 day
+ * month starting on a Saturday draws six. The popover resizes as the user pages
+ * through the year and the day under the pointer moves out from under it. Fixed
+ * at 42 because six weeks is the most any month can touch.
+ *
+ * `weekStartsOn` is 0 for Sunday and 1 for Monday.
+ */
+export declare function monthGrid(y: number, m: number, weekStartsOn?: 0 | 1): {
+    date: CalendarDate;
+    outside: boolean;
+}[];