@orvain/utils 0.0.0-stage → 0.1.1

package/dist/richText/model.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Rich-text document model shared by the React and Vue `TextAreaWithToolbar`.
+ *
+ * Every HTML string that enters the editor (a `value`, a paste, a drop, the
+ * live DOM after native typing) is read into this model and written back out
+ * by `serializeRichText`. Output is only ever produced from the model, so the
+ * allow-list is structural: text is escaped, and the only markup that can come
+ * out is `<blockquote>` around quoted paragraphs, `<p>` (optional `text-align`
+ * and a 24px `margin-left` indent), `<br>`, `<strong>`, `<em>`, `<u>` and
+ * `<span>` with validated `color` / `font-family` / `font-size`. Scripts,
+ * event handlers, URLs and every other tag or style are dropped on the way in.
+ */
+export type RichTextMark = 'bold' | 'italic' | 'underline';
+export type RichTextStyle = 'color' | 'fontFamily' | 'fontSize';
+export type RichTextAlign = 'left' | 'center' | 'right';
+/** Formatting carried by a run of text. Absent = off / inherited default. */
+export interface RichTextMarks {
+    bold?: true;
+    italic?: true;
+    underline?: true;
+    color?: string;
+    fontFamily?: string;
+    fontSize?: string;
+}
+/** A change to marks: `false` / `null` removes a mark or style. */
+export interface RichTextMarkPatch {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string | null;
+    fontFamily?: string | null;
+    fontSize?: string | null;
+}
+export interface RichTextRun {
+    /** Text; `\n` is a line break (`<br>`). */
+    text: string;
+    marks: RichTextMarks;
+}
+export interface RichTextBlock {
+    align: RichTextAlign;
+    runs: RichTextRun[];
+    /** Inside a block quote. Absent = not quoted. */
+    quote?: true;
+    /** Indent steps of {@link RICH_TEXT_INDENT_STEP}px (0 to {@link RICH_TEXT_MAX_INDENT}). Absent = 0. */
+    indent?: number;
+}
+/** One indent step, in px (`spacing.24`). */
+export declare const RICH_TEXT_INDENT_STEP = 24;
+/** Deepest indent the editor produces; the model keeps a number so more levels can follow. */
+export declare const RICH_TEXT_MAX_INDENT = 1;
+export type RichTextDoc = RichTextBlock[];
+/** A caret position: block index + character offset inside the block. */
+export interface RichTextPos {
+    block: number;
+    offset: number;
+}
+/** What the toolbar shows for the current selection. */
+export interface RichTextFormat {
+    bold: boolean;
+    italic: boolean;
+    underline: boolean;
+    align: RichTextAlign;
+    /** Every paragraph the selection touches is quoted. */
+    quote: boolean;
+    /** The smallest indent among the paragraphs the selection touches. */
+    indent: number;
+    /** `undefined` when the selection has no explicit value or mixes several. */
+    color: string | undefined;
+    fontFamily: string | undefined;
+    fontSize: string | undefined;
+}
+/** A CSS colour from the allow-list (hex, rgb[a](), a bare keyword), normalised, or `undefined`. */
+export declare function cleanRichTextColor(value: string): string | undefined;
+/** A font-family list made only of names, quotes, commas and hyphens, or `undefined`. */
+export declare function cleanRichTextFontFamily(value: string): string | undefined;
+/** A font size with a unit (px, pt, em, rem, %) inside sane bounds, or `undefined`. */
+export declare function cleanRichTextFontSize(value: string): string | undefined;
+export declare function applyMarkPatch(marks: RichTextMarks, patch: RichTextMarkPatch): RichTextMarks;
+export interface RichTextReadOptions {
+    /**
+     * Clipboard / drag-and-drop content from elsewhere: keep only bold, italic,
+     * underline and paragraphs (foreign colours, fonts and sizes are dropped)
+     * and collapse source-code whitespace the way a browser renders it.
+     */
+    foreign?: boolean;
+}
+/** Where a DOM node landed in the model; used to map selections. */
+export interface RichTextDomItem<N> {
+    node: N;
+    kind: 'text' | 'br' | 'placeholder' | 'block';
+    block: number;
+    start: number;
+    length: number;
+}
+/** Merges equal neighbouring runs and drops empty ones. */
+export declare function normalizeDoc(doc: RichTextDoc): RichTextDoc;
+/** Reads an HTML string (a value, or clipboard HTML with `foreign`) into the model. */
+export declare function parseRichText(html: string, options?: RichTextReadOptions): RichTextDoc;
+/** Reads the live editor DOM into the model, with where each node landed. */
+export declare function readRichTextDom(root: Node): {
+    doc: RichTextDoc;
+    items: RichTextDomItem<Node>[];
+};
+/** Builds output nodes of any kind (an HTML string, framework vnodes) from the model. */
+export interface RichTextRenderer<T> {
+    element(tag: RichTextTag, style: string | undefined, children: T[]): T;
+    text(text: string): T;
+}
+export type RichTextTag = 'blockquote' | 'p' | 'br' | 'strong' | 'em' | 'u' | 'span';
+/**
+ * The editor's paragraphs as renderer nodes: always at least one (empty)
+ * paragraph. An empty line needs a <br> to have height; so does a paragraph
+ * ending in a line break. Neighbouring quoted paragraphs share one
+ * `<blockquote>`.
+ */
+export declare function renderRichText<T>(doc: RichTextDoc, r: RichTextRenderer<T>): T[];
+/** The markup the editor renders: always at least one (empty) paragraph. */
+export declare function serializeRichText(doc: RichTextDoc): string;
+/** The public value: the serialized document, or `''` when there is no content. */
+export declare function richTextValue(doc: RichTextDoc): string;
+export declare function isRichTextEmpty(doc: RichTextDoc): boolean;
+/** Sanitizes an HTML string to the editor's allow-list. */
+export declare function sanitizeRichText(html: string, options?: RichTextReadOptions): string;
+/** Plain text of an HTML value: one line per paragraph, `<br>` as a newline. */
+export declare function richTextToPlainText(html: string): string;
+export declare function richTextDocText(doc: RichTextDoc): string;
+export declare const emptyBlock: (align?: RichTextAlign) => RichTextBlock;
+export declare function blockText(b: RichTextBlock): string;
+export declare function blockLength(b: RichTextBlock | undefined): number;
+/** Positions as one number: block boundaries count as one character. */
+export declare function toGlobal(doc: RichTextDoc, pos: RichTextPos): number;
+export declare function fromGlobal(doc: RichTextDoc, g: number): RichTextPos;
+export declare function docLength(doc: RichTextDoc): number;
+/** The content between two global positions, as a document fragment. */
+export declare function sliceDoc(doc: RichTextDoc, from: number, to: number): RichTextDoc;
+/**
+ * Replaces the range with a fragment. A one-block fragment goes inline; more
+ * blocks split the paragraph. Returns the new document and the caret after
+ * the inserted content.
+ */
+export declare function replaceRange(doc: RichTextDoc, from: number, to: number, fragment: RichTextDoc): {
+    doc: RichTextDoc;
+    caret: number;
+};
+/** Applies `change` to the marks of every character in the range. */
+export declare function formatRange(doc: RichTextDoc, from: number, to: number, change: (marks: RichTextMarks) => RichTextMarks): RichTextDoc;
+/** Sets the alignment of every block the range touches. */
+export declare function alignRange(doc: RichTextDoc, from: number, to: number, align: RichTextAlign): RichTextDoc;
+/** Quotes (or unquotes) every block the range touches. */
+export declare function quoteRange(doc: RichTextDoc, from: number, to: number, on: boolean): RichTextDoc;
+/**
+ * Sets the indent of every block the range touches, to `level` or to what
+ * `level(current)` returns; clamped to 0…{@link RICH_TEXT_MAX_INDENT}.
+ */
+export declare function indentRange(doc: RichTextDoc, from: number, to: number, level: number | ((current: number) => number)): RichTextDoc;
+/** Marks typed text would take at a caret: the character before it, else the first one. */
+export declare function marksAt(doc: RichTextDoc, g: number): RichTextMarks;
+/** The format of a selection: a mark is on only if every selected character has it. */
+export declare function formatOf(doc: RichTextDoc, anchor: number, focus: number, pending?: RichTextMarkPatch | null): RichTextFormat;
+/** The toolbar format for a value before the editor is mounted: the caret at the end. */
+export declare function richTextFormat(html: string, pending?: RichTextMarkPatch | null): RichTextFormat;
+//# sourceMappingURL=model.d.ts.map

package/dist/slider.d.cts

@@ -0,0 +1,18 @@
+/**
+ * Framework-neutral helpers for "draggable progress bars" (website
+ * match): Compression / Spending / Intensity progress bars become WAI-ARIA
+ * APG sliders when the consumer opts in (React `onValueChange`, Vue
+ * `interactive`). Pointer position → value, and the APG keyboard model.
+ */
+/** Rounds `value` to the nearest `step` above `min` and clamps it to [min, max]. */
+export declare function snapSliderValue(value: number, min: number, max: number, step: number): number;
+/** Value under a horizontal pointer position inside `rect` (left = min). */
+export declare function sliderValueFromPointer(clientX: number, rect: {
+    left: number;
+    width: number;
+}, min: number, max: number, step: number): number;
+/**
+ * APG slider keys: ←/↓ −step, →/↑ +step, PageDown / PageUp ∓10 steps,
+ * Home → min, End → max. Returns `null` for any other key.
+ */
+export declare function sliderValueFromKey(key: string, value: number, min: number, max: number, step: number): number | null;

package/dist/slider.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Framework-neutral helpers for "draggable progress bars" (website
+ * match): Compression / Spending / Intensity progress bars become WAI-ARIA
+ * APG sliders when the consumer opts in (React `onValueChange`, Vue
+ * `interactive`). Pointer position → value, and the APG keyboard model.
+ */
+/** Rounds `value` to the nearest `step` above `min` and clamps it to [min, max]. */
+export declare function snapSliderValue(value: number, min: number, max: number, step: number): number;
+/** Value under a horizontal pointer position inside `rect` (left = min). */
+export declare function sliderValueFromPointer(clientX: number, rect: {
+    left: number;
+    width: number;
+}, min: number, max: number, step: number): number;
+/**
+ * APG slider keys: ←/↓ −step, →/↑ +step, PageDown / PageUp ∓10 steps,
+ * Home → min, End → max. Returns `null` for any other key.
+ */
+export declare function sliderValueFromKey(key: string, value: number, min: number, max: number, step: number): number | null;
+//# sourceMappingURL=slider.d.ts.map

package/dist/tree.d.cts

@@ -0,0 +1,78 @@
+/**
+ * Framework-free tree helpers for the TreeView component (React + Vue).
+ *
+ * They implement the data side of the WAI-ARIA APG Tree View pattern
+ * (https://www.w3.org/WAI/ARIA/apg/patterns/treeview/): the list of visible
+ * rows with their aria-level / aria-setsize / aria-posinset, and the
+ * keyboard model (arrows, Home/End, `*`, typeahead). The components only
+ * render and apply the returned actions.
+ */
+export interface TreeNodeLike<T> {
+    id: string;
+    label: string;
+    children?: T[];
+}
+/** One visible row. `kind: 'add'` is the optional trailing "add child" row of an open branch. */
+export interface VisibleTreeRow<T> {
+    kind: 'node' | 'add';
+    /** Node id, or `<parentId>::add` for an add row. */
+    id: string;
+    /** The node (for an add row: its parent). */
+    node: T;
+    parentId: string | null;
+    /** aria-level, 1-based. */
+    level: number;
+    /** aria-posinset, 1-based. */
+    posinset: number;
+    /** aria-setsize. */
+    setsize: number;
+    expandable: boolean;
+    expanded: boolean;
+    /** `aria-disabled`: the row is skipped by the keyboard and cannot be activated or toggled. */
+    disabled?: boolean;
+}
+export interface FlattenTreeOptions<T> {
+    /** Whether a node can be expanded (renders `aria-expanded`). */
+    isExpandable: (node: T) => boolean;
+    /** Whether an open branch ends with an "add child" row. */
+    hasAddRow?: (node: T) => boolean;
+    /** Whether a node is disabled (skipped by the keyboard). */
+    isDisabled?: (node: T) => boolean;
+}
+/** Visible rows, depth-first, skipping the children of collapsed branches. */
+export declare function flattenVisibleTree<T extends TreeNodeLike<T>>(nodes: readonly T[], expanded: ReadonlySet<string>, options: FlattenTreeOptions<T>): VisibleTreeRow<T>[];
+/** Every node id in the tree, depth-first (used for stable DOM ids). */
+export declare function collectTreeIds<T extends TreeNodeLike<T>>(nodes: readonly T[]): string[];
+/** What a key press asks the tree to do. */
+export interface TreeKeyAction {
+    /** Move focus to this row id. */
+    focus?: string;
+    /** Expand these node ids. */
+    expand?: string[];
+    /** Collapse this node id. */
+    collapse?: string;
+    /** Activate this row (select a node, or trigger an add row). */
+    activate?: string;
+}
+/**
+ * APG Tree View keyboard model. Returns `null` when the key is not handled
+ * (let it through). Typeahead is handled separately by `createTreeTypeahead`.
+ * Disabled rows (`row.disabled`) are skipped: focus never lands on them and
+ * they are never expanded, collapsed or activated.
+ */
+export declare function treeKeyAction<T>(key: string, focusedId: string, rows: readonly VisibleTreeRow<T>[]): TreeKeyAction | null;
+/**
+ * Typeahead: returns a function that takes a printable character and the
+ * current rows, and returns the id of the next row whose label starts with
+ * the typed string (searching after the focused row, wrapping), or null.
+ */
+export declare function createTreeTypeahead(timeout?: number): <T extends {
+    label: string;
+}>(char: string, focusedId: string, rows: readonly VisibleTreeRow<T>[], labelOf?: (row: VisibleTreeRow<T>) => string) => string | null;
+/** True for a key that should feed typeahead (one printable char, no modifier). */
+export declare function isTypeaheadKey(e: {
+    key: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    altKey: boolean;
+}): boolean;

package/dist/tree.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Framework-free tree helpers for the TreeView component (React + Vue).
+ *
+ * They implement the data side of the WAI-ARIA APG Tree View pattern
+ * (https://www.w3.org/WAI/ARIA/apg/patterns/treeview/): the list of visible
+ * rows with their aria-level / aria-setsize / aria-posinset, and the
+ * keyboard model (arrows, Home/End, `*`, typeahead). The components only
+ * render and apply the returned actions.
+ */
+export interface TreeNodeLike<T> {
+    id: string;
+    label: string;
+    children?: T[];
+}
+/** One visible row. `kind: 'add'` is the optional trailing "add child" row of an open branch. */
+export interface VisibleTreeRow<T> {
+    kind: 'node' | 'add';
+    /** Node id, or `<parentId>::add` for an add row. */
+    id: string;
+    /** The node (for an add row: its parent). */
+    node: T;
+    parentId: string | null;
+    /** aria-level, 1-based. */
+    level: number;
+    /** aria-posinset, 1-based. */
+    posinset: number;
+    /** aria-setsize. */
+    setsize: number;
+    expandable: boolean;
+    expanded: boolean;
+    /** `aria-disabled`: the row is skipped by the keyboard and cannot be activated or toggled. */
+    disabled?: boolean;
+}
+export interface FlattenTreeOptions<T> {
+    /** Whether a node can be expanded (renders `aria-expanded`). */
+    isExpandable: (node: T) => boolean;
+    /** Whether an open branch ends with an "add child" row. */
+    hasAddRow?: (node: T) => boolean;
+    /** Whether a node is disabled (skipped by the keyboard). */
+    isDisabled?: (node: T) => boolean;
+}
+/** Visible rows, depth-first, skipping the children of collapsed branches. */
+export declare function flattenVisibleTree<T extends TreeNodeLike<T>>(nodes: readonly T[], expanded: ReadonlySet<string>, options: FlattenTreeOptions<T>): VisibleTreeRow<T>[];
+/** Every node id in the tree, depth-first (used for stable DOM ids). */
+export declare function collectTreeIds<T extends TreeNodeLike<T>>(nodes: readonly T[]): string[];
+/** What a key press asks the tree to do. */
+export interface TreeKeyAction {
+    /** Move focus to this row id. */
+    focus?: string;
+    /** Expand these node ids. */
+    expand?: string[];
+    /** Collapse this node id. */
+    collapse?: string;
+    /** Activate this row (select a node, or trigger an add row). */
+    activate?: string;
+}
+/**
+ * APG Tree View keyboard model. Returns `null` when the key is not handled
+ * (let it through). Typeahead is handled separately by `createTreeTypeahead`.
+ * Disabled rows (`row.disabled`) are skipped: focus never lands on them and
+ * they are never expanded, collapsed or activated.
+ */
+export declare function treeKeyAction<T>(key: string, focusedId: string, rows: readonly VisibleTreeRow<T>[]): TreeKeyAction | null;
+/**
+ * Typeahead: returns a function that takes a printable character and the
+ * current rows, and returns the id of the next row whose label starts with
+ * the typed string (searching after the focused row, wrapping), or null.
+ */
+export declare function createTreeTypeahead(timeout?: number): <T extends {
+    label: string;
+}>(char: string, focusedId: string, rows: readonly VisibleTreeRow<T>[], labelOf?: (row: VisibleTreeRow<T>) => string) => string | null;
+/** True for a key that should feed typeahead (one printable char, no modifier). */
+export declare function isTypeaheadKey(e: {
+    key: string;
+    ctrlKey: boolean;
+    metaKey: boolean;
+    altKey: boolean;
+}): boolean;
+//# sourceMappingURL=tree.d.ts.map

package/dist/types.d.cts

@@ -0,0 +1,22 @@
+/**
+ * The one size vocabulary every component uses on its `size` prop (and on
+ * sub-part props such as `headerSize`). Each component spells out the steps it
+ * draws as a literal union (so the docs list the values); a type test keeps
+ * every such union inside `Size`. Figma axis values translate as
+ * 2X-Small → `2xs`, X-Small / Extra-Small → `xs`, Small → `sm`, Medium → `md`,
+ * Large → `lg`, X-Large → `xl`, 2X-Large → `2xl`. Components whose Figma Size
+ * axis is in pixels (Avatar, Pagination, …) take pixel numbers instead.
+ */
+export type Size = '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export type Variant = 'primary' | 'secondary' | 'ghost' | 'destructive' | 'outline';
+export type ColorScheme = 'light' | 'dark';
+export type Intent = 'default' | 'success' | 'warning' | 'error' | 'info';
+/** Base props every component accepts */
+export interface ComponentBaseProps {
+    /** Additional CSS class names */
+    class?: string;
+    /** Inline styles */
+    style?: string | Record<string, string>;
+    /** Test ID for automated testing */
+    'data-testid'?: string;
+}

package/dist/types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The one size vocabulary every component uses on its `size` prop (and on
+ * sub-part props such as `headerSize`). Each component spells out the steps it
+ * draws as a literal union (so the docs list the values); a type test keeps
+ * every such union inside `Size`. Figma axis values translate as
+ * 2X-Small → `2xs`, X-Small / Extra-Small → `xs`, Small → `sm`, Medium → `md`,
+ * Large → `lg`, X-Large → `xl`, 2X-Large → `2xl`. Components whose Figma Size
+ * axis is in pixels (Avatar, Pagination, …) take pixel numbers instead.
+ */
+export type Size = '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export type Variant = 'primary' | 'secondary' | 'ghost' | 'destructive' | 'outline';
+export type ColorScheme = 'light' | 'dark';
+export type Intent = 'default' | 'success' | 'warning' | 'error' | 'info';
+/** Base props every component accepts */
+export interface ComponentBaseProps {
+    /** Additional CSS class names */
+    class?: string;
+    /** Inline styles */
+    style?: string | Record<string, string>;
+    /** Test ID for automated testing */
+    'data-testid'?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@orvain/utils",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Orvain Design System — shared utilities, types and a11y helpers",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.1",
+    "typescript": "^5.5.4",
+    "vite": "^5.4.0",
+    "@orvain/tokens": "^0.1.1"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ozzy-UI/orvain.git",
+    "directory": "packages/utils"
+  },
+  "homepage": "https://github.com/Ozzy-UI/orvain/tree/main/packages/utils#readme",
+  "bugs": {
+    "url": "https://github.com/Ozzy-UI/orvain/issues"
+  },
+  "keywords": [
+    "design-system",
+    "utilities",
+    "accessibility"
+  ],
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly --outDir dist && node ../../scripts/fix-declarations.mjs dist",
+    "dev": "vite build --watch",
+    "lint": "eslint src",
+    "clean": "rimraf dist"
+  }
 }