@sewadah/selaras 0.1.1 → 0.3.0

package/dist/runtime/utils/color-registry.d.ts

@@ -0,0 +1,62 @@
+import type { ThemeTokenOverrides } from './functional-tokens.js';
+/**
+ * Framework-independent semantic color contracts.
+ *
+ * This module deliberately contains no Vue, Nuxt or Tailwind imports. It is
+ * the normalization boundary that build-time adapters and runtime CSS
+ * bindings can share without putting a token resolver in component bundles.
+ */
+export declare const builtinColorNames: readonly ["primary", "secondary", "success", "info", "warning", "danger", "neutral"];
+export type BuiltinColorName = typeof builtinColorNames[number];
+declare global {
+    interface SelarasColorRegistry {
+    }
+}
+export type ColorRole = BuiltinColorName | Extract<keyof SelarasColorRegistry, string>;
+export interface ColorRecipe {
+    fill: string;
+    fillHover: string;
+    fillPressed: string;
+    onFill: string;
+    /** Essential unpaired graphics such as progress and selection indicators. */
+    indicator: string;
+    subtle: string;
+    subtleHover: string;
+    subtlePressed: string;
+    onSubtle: string;
+    text: string;
+    textHover: string;
+    textPressed: string;
+    border: string;
+    focus: string;
+}
+export type ColorRecipeInput = Pick<ColorRecipe, 'fill' | 'onFill' | 'subtle' | 'onSubtle' | 'text' | 'border'> & Partial<Pick<ColorRecipe, 'fillHover' | 'fillPressed' | 'indicator' | 'subtleHover' | 'subtlePressed' | 'textHover' | 'textPressed' | 'focus'>>;
+export type RuntimeColorOverrides = Partial<Record<ColorRole, Partial<ColorRecipeInput>>>;
+export interface RuntimeThemeMode extends ThemeTokenOverrides {
+    colors?: RuntimeColorOverrides;
+}
+export interface RuntimeTokenOverrides {
+    light?: RuntimeThemeMode;
+    dark?: RuntimeThemeMode;
+}
+/** Composes managed scope leaves without resolving authored CSS expressions. */
+export declare function mergeRuntimeTokenOverrides(parent?: RuntimeTokenOverrides, local?: RuntimeTokenOverrides): RuntimeTokenOverrides;
+export interface ColorModePair<T> {
+    light: T;
+    dark: T;
+}
+export declare function assertColorRoleName(name: string): asserts name is string;
+/** Compiles omitted web recipe leaves into dependencies on resolved bindings. */
+export declare function normalizeColorRecipe(input: ColorRecipeInput): ColorRecipe;
+export declare function createColorRegistry<T extends Record<string, ColorModePair<ColorRecipeInput>>>(custom: T): { [K in keyof T]: ColorModePair<ColorRecipe>; };
+/** Exact owners rematerialize effective leaves, including across DOM portals. */
+export declare function generateRuntimeTokenOverrideCss(overrides: RuntimeTokenOverrides, scopeSelector?: string): string;
+/**
+ * Serializes normalized role recipes into public owner-local read values and
+ * the private selected-role bindings consumed by role-capable components.
+ * Role-specific public inputs inherit from the DOM; authored defaults resolve
+ * at managed owners so local external variables remain usable.
+ * The output is deterministic so Nuxt template
+ * hashes and HMR invalidation do not change with object insertion order.
+ */
+export declare function generateColorRoleCss(registry: Record<string, ColorModePair<ColorRecipe>>): string;

package/dist/runtime/utils/color-registry.js

@@ -0,0 +1,191 @@
+import { functionalTokenEntries, mergeFunctionalTokenOverrides } from "./functional-tokens.js";
+export const builtinColorNames = ["primary", "secondary", "success", "info", "warning", "danger", "neutral"];
+export function mergeRuntimeTokenOverrides(parent = {}, local = {}) {
+  const result = {};
+  for (const mode of ["light", "dark"]) {
+    const functional = mergeFunctionalTokenOverrides(parent[mode], local[mode]);
+    const roles = /* @__PURE__ */ new Set([...Object.keys(parent[mode]?.colors ?? {}), ...Object.keys(local[mode]?.colors ?? {})]);
+    if (roles.size === 0 && Object.keys(functional).length === 0)
+      continue;
+    const colors = {};
+    for (const role of roles) {
+      assertColorRoleName(role);
+      const key = role;
+      colors[key] = Object.fromEntries(
+        [...Object.entries(parent[mode]?.colors?.[key] ?? {}), ...Object.entries(local[mode]?.colors?.[key] ?? {})].filter(([, value]) => value !== void 0)
+      );
+    }
+    result[mode] = { ...functional, ...roles.size ? { colors } : {} };
+  }
+  return result;
+}
+const roleNamePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const reservedRoleNames = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+const requiredRecipeFields = ["fill", "onFill", "subtle", "onSubtle", "text", "border"];
+export function assertColorRoleName(name) {
+  if (!roleNamePattern.test(name) || reservedRoleNames.has(name))
+    throw new Error(`Invalid Selaras color role "${name}". Use lowercase kebab-case, for example "brand-accent".`);
+}
+export function normalizeColorRecipe(input) {
+  for (const field of requiredRecipeFields) {
+    if (typeof input?.[field] !== "string" || input[field].length === 0)
+      throw new Error(`Invalid Selaras color recipe: "${field}" must be a non-empty string.`);
+  }
+  return {
+    fill: input.fill,
+    // Keep omitted leaves as dependencies on the resolved state, rather than
+    // copying authored values. CSS overrides then propagate through the chain.
+    fillHover: input.fillHover ?? "var(--_selaras-color-fill)",
+    fillPressed: input.fillPressed ?? "var(--_selaras-color-fill-hover)",
+    onFill: input.onFill,
+    // A recipe's border is already authored for visibility against its
+    // surrounding surface, making it the safe shorthand for unpaired marks.
+    indicator: input.indicator ?? "var(--_selaras-color-border)",
+    subtle: input.subtle,
+    subtleHover: input.subtleHover ?? "var(--_selaras-color-subtle)",
+    subtlePressed: input.subtlePressed ?? "var(--_selaras-color-subtle-hover)",
+    onSubtle: input.onSubtle,
+    text: input.text,
+    textHover: input.textHover ?? "var(--_selaras-color-text)",
+    textPressed: input.textPressed ?? "var(--_selaras-color-text-hover)",
+    border: input.border,
+    focus: input.focus ?? "var(--_selaras-color-text)"
+  };
+}
+export function createColorRegistry(custom) {
+  for (const name of Object.keys(custom))
+    assertColorRoleName(name);
+  return Object.fromEntries(Object.entries(custom).map(([name, modes]) => [name, {
+    light: normalizeColorRecipe(modes.light),
+    dark: normalizeColorRecipe(modes.dark)
+  }]));
+}
+const generatedRoleFields = [
+  "fill",
+  "fill-hover",
+  "fill-pressed",
+  "on-fill",
+  "indicator",
+  "subtle",
+  "subtle-hover",
+  "subtle-pressed",
+  "on-subtle",
+  "text",
+  "text-hover",
+  "text-pressed",
+  "border",
+  "focus"
+];
+function roleFieldValue(recipe, field) {
+  const property = field.replace(/-([a-z])/g, (_, character) => character.toUpperCase());
+  return recipe[property];
+}
+const selectedRoleDependencyPattern = /^var\(--_selaras-color-([a-z-]+)\)$/;
+function resolvedRoleProperty(role, field) {
+  return `--selaras-resolved-color-${role}-${field}`;
+}
+function resolvedRoleValue(role, recipe, field) {
+  return roleFieldValue(recipe, field).replace(selectedRoleDependencyPattern, (_match, dependency) => `var(${resolvedRoleProperty(role, dependency)})`);
+}
+function assertCssValue(value) {
+  if (typeof value !== "string" || value.trim().length === 0)
+    throw new Error("Invalid Selaras token value: expected a non-empty CSS string.");
+  if (/[;{}\r\n]/.test(value))
+    throw new Error("Invalid Selaras token value: declaration delimiters are not allowed.");
+}
+function overrideRule(selector, role, overrides) {
+  const declarations = Object.entries(overrides).map(([field, value]) => {
+    if (value === void 0)
+      return void 0;
+    assertCssValue(value);
+    const kebab = field.replace(/[A-Z]/g, (character) => `-${character.toLowerCase()}`);
+    return `  --selaras-color-${role}-${kebab}: ${value};`;
+  }).filter(Boolean);
+  return declarations.length > 0 ? `${selector} {
+${declarations.join("\n")}
+}` : void 0;
+}
+export function generateRuntimeTokenOverrideCss(overrides, scopeSelector = '[data-selaras-theme="global"]') {
+  const rules = [];
+  const owner = scopeSelector.trim();
+  const roles = /* @__PURE__ */ new Set([...Object.keys(overrides.light?.colors ?? {}), ...Object.keys(overrides.dark?.colors ?? {})]);
+  const functional = {
+    light: Object.fromEntries(functionalTokenEntries(overrides.light)),
+    dark: Object.fromEntries(functionalTokenEntries(overrides.dark))
+  };
+  const functionalFields = [.../* @__PURE__ */ new Set([...Object.keys(functional.light), ...Object.keys(functional.dark)])].sort();
+  for (const mode of ["light", "dark"]) {
+    const selector = mode === "dark" ? `:root.dark ${owner}:where(:not([data-selaras-mode]), [data-selaras-mode="root"]),
+${owner}:where([data-selaras-mode="dark"])` : `${owner}:where(:not([data-selaras-mode]), [data-selaras-mode="root"], [data-selaras-mode="light"])`;
+    const functionalDeclarations = functionalFields.map((field) => {
+      const value = functional[mode][field] ?? "initial";
+      assertCssValue(value);
+      return `  ${field}: ${value};`;
+    });
+    if (functionalDeclarations.length) {
+      const functionalSelector = owner === '[data-selaras-theme="global"]' ? `${selector},
+${mode === "dark" ? ":root.dark" : ":root"}` : selector;
+      rules.push(`${functionalSelector} {
+${functionalDeclarations.join("\n")}
+}`);
+    }
+    const colors = overrides[mode]?.colors;
+    const colorSelector = owner === '[data-selaras-theme="global"]' ? `${selector},
+${mode === "dark" ? ":root.dark" : ":root"}` : selector;
+    for (const role of [...roles].sort()) {
+      assertColorRoleName(role);
+      const key = role;
+      const fields = new Set([
+        ...Object.entries(overrides.light?.colors?.[key] ?? {}),
+        ...Object.entries(overrides.dark?.colors?.[key] ?? {})
+      ].filter(([, value]) => value !== void 0).map(([field]) => field));
+      const effective = Object.fromEntries([...fields].map((field) => [field, colors?.[key]?.[field] ?? "initial"]));
+      const rule = overrideRule(colorSelector, role, effective);
+      if (rule)
+        rules.push(rule);
+    }
+  }
+  return rules.length > 0 ? `@layer theme {
+${rules.join("\n\n")}
+}
+` : "";
+}
+function roleReadRule(selector, registry, mode, changedOnly = false) {
+  const declarations = [];
+  for (const role of Object.keys(registry).sort()) {
+    const recipes = registry[role];
+    for (const field of generatedRoleFields) {
+      const value = resolvedRoleValue(role, recipes[mode], field);
+      if (changedOnly && value === resolvedRoleValue(role, recipes.light, field))
+        continue;
+      declarations.push(`  ${resolvedRoleProperty(role, field)}: var(--selaras-color-${role}-${field}, ${value});`);
+    }
+  }
+  return declarations.length ? `${selector} {
+${declarations.join("\n")}
+}` : void 0;
+}
+function selectedRoleRule(role) {
+  const declarations = generatedRoleFields.map((field) => `  --_selaras-color-${field}: var(--selaras-color-${role}-${field}, var(${resolvedRoleProperty(role, field)}));`).join("\n");
+  return `[data-selaras-color="${role}"] {
+${declarations}
+}`;
+}
+export function generateColorRoleCss(registry) {
+  const roles = Object.keys(registry).sort();
+  for (const role of roles)
+    assertColorRoleName(role);
+  const rules = [];
+  const lightReads = roleReadRule(":root,\n[data-selaras-theme]", registry, "light");
+  if (lightReads)
+    rules.push(lightReads);
+  const darkReads = roleReadRule(':root.dark,\n:root.dark [data-selaras-theme]:where(:not([data-selaras-mode]), [data-selaras-mode="root"]),\n[data-selaras-theme]:where([data-selaras-mode="dark"])', registry, "dark", true);
+  if (darkReads)
+    rules.push(darkReads);
+  for (const role of roles)
+    rules.push(selectedRoleRule(role));
+  return rules.length > 0 ? `@layer theme {
+${rules.join("\n\n")}
+}
+` : "";
+}

package/dist/runtime/utils/dtcg-colors.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The structured, already-resolved DTCG color subset Selaras can serialize
+ * today. Resolution, alias traversal and context selection belong to the
+ * caller's DTCG processor, not the component runtime.
+ */
+export type DtcgColorSpace = 'srgb' | 'srgb-linear' | 'oklch';
+export type DtcgColorComponent = number | 'none';
+export interface DtcgResolvedColor {
+    colorSpace: DtcgColorSpace;
+    components: readonly [DtcgColorComponent, DtcgColorComponent, DtcgColorComponent];
+    /** Omitted alpha means fully opaque; DTCG does not permit `none` here. */
+    alpha?: number;
+    /** Optional six-digit fallback required by DTCG when provided. */
+    hex?: string;
+}
+export interface DtcgColorConversionOptions {
+    /** Source path included in validation errors. @default '$value' */
+    path?: string;
+}
+/**
+ * Converts a resolved structured DTCG color to a browser CSS value.
+ * It deliberately accepts no CSS strings, aliases, token groups or Resolver
+ * documents: pass a resolved `$value` at the semantic mapping boundary.
+ */
+export declare function dtcgColorToCss(value: unknown, options?: DtcgColorConversionOptions): string;

package/dist/runtime/utils/dtcg-colors.js

@@ -0,0 +1,40 @@
+function invalid(path, message) {
+  throw new Error(`Invalid resolved DTCG color at ${path}: ${message}`);
+}
+function assertComponent(value, path) {
+  if (value !== "none" && (typeof value !== "number" || !Number.isFinite(value)))
+    invalid(path, 'components must be finite numbers or "none".');
+}
+function assertRange(value, path, minimum, maximum, inclusiveMaximum = true) {
+  if (value === "none")
+    return;
+  if (value < minimum || value > maximum || !inclusiveMaximum && value === maximum)
+    invalid(path, `must be within ${inclusiveMaximum ? `[${minimum}, ${maximum}]` : `[${minimum}, ${maximum})`}.`);
+}
+export function dtcgColorToCss(value, options = {}) {
+  const path = options.path ?? "$value";
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    invalid(path, "expected a structured color value after reference resolution.");
+  const color = value;
+  if (color.colorSpace !== "srgb" && color.colorSpace !== "srgb-linear" && color.colorSpace !== "oklch")
+    invalid(path, 'unsupported colorSpace; supported values are "srgb", "srgb-linear" and "oklch".');
+  if (!Array.isArray(color.components) || color.components.length !== 3)
+    invalid(path, "components must contain exactly three values.");
+  for (const [index, component] of color.components.entries())
+    assertComponent(component, `${path}.components[${index}]`);
+  if (color.colorSpace === "srgb" || color.colorSpace === "srgb-linear") {
+    for (const [index, component] of color.components.entries())
+      assertRange(component, `${path}.components[${index}]`, 0, 1);
+  } else {
+    assertRange(color.components[0], `${path}.components[0]`, 0, 1);
+    assertRange(color.components[1], `${path}.components[1]`, 0, Number.POSITIVE_INFINITY);
+    assertRange(color.components[2], `${path}.components[2]`, 0, 360, false);
+  }
+  if (color.alpha !== void 0 && (typeof color.alpha !== "number" || !Number.isFinite(color.alpha) || color.alpha < 0 || color.alpha > 1))
+    invalid(`${path}.alpha`, "must be a number within [0, 1].");
+  if (color.hex !== void 0 && (typeof color.hex !== "string" || !/^#[0-9a-f]{6}$/i.test(color.hex)))
+    invalid(`${path}.hex`, "must be a six-digit CSS hex fallback.");
+  const alpha = color.alpha === void 0 ? "" : ` / ${color.alpha}`;
+  const components = color.components.join(" ");
+  return color.colorSpace === "oklch" ? `oklch(${components}${alpha})` : `color(${color.colorSpace} ${components}${alpha})`;
+}

package/dist/runtime/utils/file-icons.d.ts

@@ -0,0 +1,8 @@
+export declare const defaultFileIcons: Record<string, string>;
+/**
+ * Resolves a file-type icon for a code block, preferring a filename's own
+ * extension (the more specific signal) over the fence's `language`. Returns
+ * undefined when neither maps to a known type, so callers can render no icon
+ * rather than a misleading fallback.
+ */
+export declare function resolveFileIcon(language?: string, filename?: string): string | undefined;

package/dist/runtime/utils/file-icons.js

@@ -0,0 +1,131 @@
+export const defaultFileIcons = {
+  "vue": "vscode-icons:file-type-vue",
+  "ts": "vscode-icons:file-type-typescript",
+  "typescript": "vscode-icons:file-type-typescript",
+  "mts": "vscode-icons:file-type-typescript",
+  "cts": "vscode-icons:file-type-typescript",
+  "tsx": "vscode-icons:file-type-reactts",
+  "js": "vscode-icons:file-type-js",
+  "javascript": "vscode-icons:file-type-js",
+  "mjs": "vscode-icons:file-type-js",
+  "cjs": "vscode-icons:file-type-js",
+  "jsx": "vscode-icons:file-type-reactjs",
+  "html": "vscode-icons:file-type-html",
+  "htm": "vscode-icons:file-type-html",
+  "css": "vscode-icons:file-type-css",
+  "scss": "vscode-icons:file-type-scss",
+  "sass": "vscode-icons:file-type-sass",
+  "less": "vscode-icons:file-type-less",
+  "json": "vscode-icons:file-type-json",
+  "jsonc": "vscode-icons:file-type-json",
+  "json5": "vscode-icons:file-type-json",
+  "md": "vscode-icons:file-type-markdown",
+  "markdown": "vscode-icons:file-type-markdown",
+  "mdx": "vscode-icons:file-type-markdown",
+  "bash": "vscode-icons:file-type-shell",
+  "sh": "vscode-icons:file-type-shell",
+  "shell": "vscode-icons:file-type-shell",
+  "zsh": "vscode-icons:file-type-shell",
+  "console": "vscode-icons:file-type-shell",
+  "terminal": "vscode-icons:file-type-shell",
+  "python": "vscode-icons:file-type-python",
+  "py": "vscode-icons:file-type-python",
+  "yaml": "vscode-icons:file-type-yaml",
+  "yml": "vscode-icons:file-type-yaml",
+  "toml": "vscode-icons:file-type-toml",
+  "ini": "vscode-icons:file-type-ini",
+  "cfg": "vscode-icons:file-type-config",
+  "conf": "vscode-icons:file-type-config",
+  "config": "vscode-icons:file-type-config",
+  "env": "vscode-icons:file-type-dotenv",
+  "dotenv": "vscode-icons:file-type-dotenv",
+  "go": "vscode-icons:file-type-go",
+  "rust": "vscode-icons:file-type-rust",
+  "rs": "vscode-icons:file-type-rust",
+  "php": "vscode-icons:file-type-php",
+  "ruby": "vscode-icons:file-type-ruby",
+  "rb": "vscode-icons:file-type-ruby",
+  "sql": "vscode-icons:file-type-sql",
+  "docker": "vscode-icons:file-type-docker",
+  "dockerfile": "vscode-icons:file-type-docker",
+  "svelte": "vscode-icons:file-type-svelte",
+  "astro": "vscode-icons:file-type-astro",
+  "xml": "vscode-icons:file-type-xml",
+  "svg": "vscode-icons:file-type-svg",
+  "java": "vscode-icons:file-type-java",
+  "kotlin": "vscode-icons:file-type-kotlin",
+  "kt": "vscode-icons:file-type-kotlin",
+  "swift": "vscode-icons:file-type-swift",
+  "csharp": "vscode-icons:file-type-csharp",
+  "cs": "vscode-icons:file-type-csharp",
+  "cpp": "vscode-icons:file-type-cpp",
+  "c++": "vscode-icons:file-type-cpp",
+  "c": "vscode-icons:file-type-c",
+  "vim": "vscode-icons:file-type-vim",
+  "lua": "vscode-icons:file-type-lua",
+  "nginx": "vscode-icons:file-type-nginx",
+  "graphql": "vscode-icons:file-type-graphql",
+  "gql": "vscode-icons:file-type-graphql",
+  "prisma": "vscode-icons:file-type-prisma",
+  "powershell": "vscode-icons:file-type-powershell",
+  "ps1": "vscode-icons:file-type-powershell",
+  "r": "vscode-icons:file-type-r",
+  "elixir": "vscode-icons:file-type-elixir",
+  "ex": "vscode-icons:file-type-elixir",
+  "exs": "vscode-icons:file-type-elixir",
+  "erlang": "vscode-icons:file-type-erlang",
+  "erl": "vscode-icons:file-type-erlang",
+  "haskell": "vscode-icons:file-type-haskell",
+  "hs": "vscode-icons:file-type-haskell",
+  "scala": "vscode-icons:file-type-scala",
+  "julia": "vscode-icons:file-type-julia",
+  "jl": "vscode-icons:file-type-julia",
+  "zig": "vscode-icons:file-type-zig",
+  "nim": "vscode-icons:file-type-nim",
+  "crystal": "vscode-icons:file-type-crystal",
+  "solidity": "vscode-icons:file-type-solidity",
+  "sol": "vscode-icons:file-type-solidity",
+  "terraform": "vscode-icons:file-type-terraform",
+  "tf": "vscode-icons:file-type-terraform",
+  "cmake": "vscode-icons:file-type-cmake",
+  "wasm": "vscode-icons:file-type-wasm",
+  "text": "vscode-icons:file-type-text",
+  "txt": "vscode-icons:file-type-text",
+  "plaintext": "vscode-icons:file-type-text",
+  "plain": "vscode-icons:file-type-text",
+  "output": "vscode-icons:file-type-text",
+  "ansi": "vscode-icons:file-type-text",
+  "diff": "vscode-icons:file-type-diff",
+  "patch": "vscode-icons:file-type-diff",
+  "log": "vscode-icons:file-type-log",
+  "image": "vscode-icons:file-type-image",
+  "audio": "vscode-icons:file-type-audio",
+  "video": "vscode-icons:file-type-video",
+  "font": "vscode-icons:file-type-font",
+  "zip": "vscode-icons:file-type-zip",
+  "git": "vscode-icons:file-type-git",
+  "gitignore": "vscode-icons:file-type-git",
+  "npm": "vscode-icons:file-type-npm",
+  "nuxt": "vscode-icons:file-type-nuxt",
+  "ansible": "vscode-icons:file-type-ansible",
+  "bicep": "vscode-icons:file-type-bicep"
+};
+function normalizeFileIconKey(value) {
+  const key = value?.trim().toLowerCase().replace(/^\./, "");
+  return key || void 0;
+}
+function extensionOf(filename) {
+  if (!filename)
+    return void 0;
+  const base = filename.split(/[\\/]/).pop() ?? filename;
+  const dot = base.lastIndexOf(".");
+  return dot > 0 ? base.slice(dot + 1) : base.replace(/^\./, "");
+}
+export function resolveFileIcon(language, filename) {
+  for (const candidate of [extensionOf(filename), language]) {
+    const key = normalizeFileIconKey(candidate);
+    if (key && defaultFileIcons[key])
+      return defaultFileIcons[key];
+  }
+  return void 0;
+}

package/dist/runtime/utils/functional-tokens.d.ts

@@ -0,0 +1,26 @@
+/** Functional colors are independent of a component's selected intent role. */
+export declare const functionalTokenGroups: {
+    readonly surface: readonly ["canvas", "default", "elevated", "inverted"];
+    readonly text: readonly ["default", "muted", "inverted"];
+    readonly border: readonly ["default", "muted", "hover"];
+};
+/** Geometry is scoped with functional colors because overlays cross portals. */
+export declare const geometryTokenGroups: {
+    readonly radius: readonly ["base", "sm", "md", "lg", "full"];
+    readonly shadow: readonly ["sm", "md", "lg"];
+    readonly zIndex: readonly ["modal-overlay", "modal", "dropdown", "tooltip", "toast"];
+};
+/** Partial CSS-valued functional inputs for one semantic mode. */
+export type FunctionalTokenOverrides = {
+    -readonly [K in keyof typeof functionalTokenGroups]?: Partial<Record<typeof functionalTokenGroups[K][number], string>>;
+} & {
+    /** Background behind a modal surface, independently of its content surface. */
+    scrim?: string;
+};
+export type GeometryTokenOverrides = {
+    -readonly [K in keyof typeof geometryTokenGroups]?: Partial<Record<typeof geometryTokenGroups[K][number], string>>;
+};
+export type ThemeTokenOverrides = FunctionalTokenOverrides & GeometryTokenOverrides;
+export declare function mergeFunctionalTokenOverrides(parent?: ThemeTokenOverrides, local?: ThemeTokenOverrides): ThemeTokenOverrides;
+/** Known public CSS inputs; defaults belong to owner-local resolved bindings. */
+export declare function functionalTokenEntries(overrides?: ThemeTokenOverrides): [string, string][];

package/dist/runtime/utils/functional-tokens.js

@@ -0,0 +1,54 @@
+export const functionalTokenGroups = {
+  surface: ["canvas", "default", "elevated", "inverted"],
+  text: ["default", "muted", "inverted"],
+  border: ["default", "muted", "hover"]
+};
+export const geometryTokenGroups = {
+  radius: ["base", "sm", "md", "lg", "full"],
+  shadow: ["sm", "md", "lg"],
+  zIndex: ["modal-overlay", "modal", "dropdown", "tooltip", "toast"]
+};
+export function mergeFunctionalTokenOverrides(parent = {}, local = {}) {
+  const result = {};
+  for (const group of Object.keys(functionalTokenGroups)) {
+    const values = Object.fromEntries(
+      [...Object.entries(parent[group] ?? {}), ...Object.entries(local[group] ?? {})].filter(([, value]) => value !== void 0)
+    );
+    if (Object.keys(values).length)
+      result[group] = values;
+  }
+  const scrim = local.scrim ?? parent.scrim;
+  if (scrim !== void 0)
+    result.scrim = scrim;
+  for (const group of Object.keys(geometryTokenGroups)) {
+    const values = Object.fromEntries(
+      [...Object.entries(parent[group] ?? {}), ...Object.entries(local[group] ?? {})].filter(([, value]) => value !== void 0)
+    );
+    if (Object.keys(values).length)
+      result[group] = values;
+  }
+  return result;
+}
+export function functionalTokenEntries(overrides = {}) {
+  const entries = [];
+  for (const group of Object.keys(functionalTokenGroups)) {
+    const values = overrides[group];
+    for (const leaf of functionalTokenGroups[group]) {
+      const value = values?.[leaf];
+      if (value !== void 0)
+        entries.push([`--selaras-${group}-${leaf}`, value]);
+    }
+  }
+  if (overrides.scrim !== void 0)
+    entries.push(["--selaras-scrim", overrides.scrim]);
+  for (const group of Object.keys(geometryTokenGroups)) {
+    const values = overrides[group];
+    const prefix = group === "zIndex" ? "z" : group;
+    for (const leaf of geometryTokenGroups[group]) {
+      const value = values?.[leaf];
+      if (value !== void 0)
+        entries.push([`--selaras-${prefix}-${leaf}`, value]);
+    }
+  }
+  return entries;
+}

package/dist/runtime/utils/icons.d.ts

@@ -35,4 +35,7 @@ export interface IconRegistry {
     more: string;
     sidebarCollapse: string;
 }
+export declare const feedbackIntentNames: readonly ["success", "danger", "warning", "info"];
+export type FeedbackIntent = typeof feedbackIntentNames[number];
+export declare function isFeedbackIntent(value: string): value is FeedbackIntent;
 export declare const defaultIcons: IconRegistry;

package/dist/runtime/utils/icons.js

@@ -1,3 +1,7 @@
+export const feedbackIntentNames = ["success", "danger", "warning", "info"];
+export function isFeedbackIntent(value) {
+  return feedbackIntentNames.includes(value);
+}
 export const defaultIcons = {
   close: "hugeicons:cancel-01",
   check: "hugeicons:tick-02",

package/dist/runtime/utils/injection-keys.d.ts

@@ -1,4 +1,6 @@
 import type { ComputedRef, InjectionKey, Ref } from 'vue';
+import type { ThemeDefaults, ThemeUiOverrides } from '../theme-config.js';
+import type { RuntimeTokenOverrides } from './color-registry.js';
 export declare const AVATAR_SIZE_INJECTION_KEY: InjectionKey<ComputedRef<'sm' | 'md' | 'lg' | undefined>>;
 /**
  * Shared from DashboardGroup down to DashboardSidebar, DashboardPanel, and
@@ -58,12 +60,19 @@ export declare const DASHBOARD_INJECTION_KEY: InjectionKey<DashboardContext>;
  * a pre-merged bag: this lets the read side walk the *whole* ancestor
  * chain and compose overrides in the correct outermost-to-innermost
  * order (see useComponentTheme's own collectThemeChain), so nesting two
- * STheme components inherits an outer one's unset slots/props instead of
+ * STheme components inherits an outer one's unset slots/defaults instead of
  * an inner one wholesale replacing it.
  */
 export interface ThemeContext {
-    ui?: Partial<Record<string, object>>;
-    props?: Partial<Record<string, Record<string, unknown>>>;
+    ui?: ThemeUiOverrides;
+    defaults?: ThemeDefaults;
+    scopeId?: string;
+    /** `root` follows the document root; explicit modes inherit logically. */
+    mode?: 'root' | 'light' | 'dark';
+    /** Effective managed tokens from explicit DOM scopes only. */
+    tokens?: RuntimeTokenOverrides;
     parent?: ThemeContext;
+    /** Internal snapshot boundary: its chain already contains global UI/defaults. */
+    replaceGlobal?: boolean;
 }
 export declare const THEME_INJECTION_KEY: InjectionKey<ComputedRef<ThemeContext>>;

package/dist/runtime/utils/native-input.d.ts

@@ -0,0 +1,5 @@
+/** Fallthrough keys that belong on a wrapped text-like native input. */
+export declare function isNativeInputAttr(key: string): boolean;
+export declare function isNativeInputEvent(key: string): boolean;
+/** Accessible naming and description belong on the wrapped input, not its layout root. */
+export declare function isNativeInputA11yAttr(key: string): boolean;

package/dist/runtime/utils/native-input.js

@@ -0,0 +1,32 @@
+const nativeInputAttributes = /* @__PURE__ */ new Set([
+  "autocomplete",
+  "autocapitalize",
+  "autocorrect",
+  "form",
+  "inputmode",
+  "list",
+  "maxlength",
+  "minlength",
+  "pattern",
+  "readonly",
+  "required",
+  "spellcheck",
+  "step"
+]);
+const nativeInputEvents = /^on(?:BeforeInput|Change|CompositionEnd|CompositionStart|CompositionUpdate|Focus|Input|KeyDown|KeyUp|Paste|Select|Blur)$/;
+const nativeInputAccessibilityAttributes = /* @__PURE__ */ new Set([
+  "aria-label",
+  "aria-labelledby",
+  "aria-describedby",
+  "aria-errormessage",
+  "aria-details"
+]);
+export function isNativeInputAttr(key) {
+  return nativeInputAttributes.has(key) || nativeInputEvents.test(key);
+}
+export function isNativeInputEvent(key) {
+  return nativeInputEvents.test(key);
+}
+export function isNativeInputA11yAttr(key) {
+  return nativeInputAccessibilityAttributes.has(key);
+}

package/dist/runtime/utils/navigation-menu.d.ts

@@ -2,6 +2,9 @@ export interface NavigationMenuItem {
     label: string;
     icon?: string;
     to?: string;
+    target?: string;
+    rel?: string;
+    ariaLabel?: string;
     disabled?: boolean;
     /** Force active state - otherwise auto-detected against the current route when `to` is set. */
     active?: boolean;

package/dist/runtime/utils/programmatic-theme.d.ts

@@ -0,0 +1,17 @@
+import type { ThemeDefaults, ThemeUiOverrides } from '../theme-config.js';
+import type { RuntimeTokenOverrides } from './color-registry.js';
+export interface ProgrammaticThemeLayer {
+    ui?: ThemeUiOverrides;
+    defaults?: ThemeDefaults;
+}
+/** @internal */
+export interface ProgrammaticThemeSnapshot {
+    layers: ProgrammaticThemeLayer[];
+    tokens?: RuntimeTokenOverrides;
+    mode: 'root' | 'light' | 'dark';
+}
+/**
+ * Captures injection access during setup, then snapshots its current effective
+ * presentation when an imperative operation is actually queued.
+ */
+export declare function useProgrammaticThemeSnapshot(): () => ProgrammaticThemeSnapshot;