@sewadah/selaras 0.1.1 → 0.3.0

package/dist/runtime/utils/programmatic-theme.js

@@ -0,0 +1,59 @@
+import { hasInjectionContext, inject, toRaw } from "vue";
+import { useAppConfig } from "#imports";
+import { THEME_INJECTION_KEY } from "./injection-keys.js";
+function cloneSnapshotValue(value, seen = /* @__PURE__ */ new WeakMap()) {
+  if (value === null || typeof value !== "object")
+    return value;
+  const raw = toRaw(value);
+  const existing = seen.get(raw);
+  if (existing)
+    return existing;
+  if (Array.isArray(raw)) {
+    const result2 = [];
+    seen.set(raw, result2);
+    for (const item of raw)
+      result2.push(cloneSnapshotValue(item, seen));
+    return result2;
+  }
+  const prototype = Object.getPrototypeOf(raw);
+  if (prototype !== Object.prototype && prototype !== null)
+    return raw;
+  const result = {};
+  seen.set(raw, result);
+  for (const key of Reflect.ownKeys(raw))
+    result[key] = cloneSnapshotValue(raw[key], seen);
+  return result;
+}
+function contextChain(context) {
+  const chain = [];
+  for (let current = context; current; current = current.parent)
+    chain.unshift(current);
+  return chain;
+}
+export function useProgrammaticThemeSnapshot() {
+  const appConfig = useAppConfig();
+  const injected = hasInjectionContext() ? inject(THEME_INJECTION_KEY, void 0) : void 0;
+  return function snapshotProgrammaticTheme() {
+    const current = injected?.value;
+    const layers = [];
+    if (!current?.replaceGlobal && (appConfig.selaras?.ui || appConfig.selaras?.defaults)) {
+      layers.push(cloneSnapshotValue({
+        ui: appConfig.selaras.ui,
+        defaults: appConfig.selaras.defaults
+      }));
+    }
+    for (const context of contextChain(current)) {
+      if (context.ui || context.defaults) {
+        layers.push(cloneSnapshotValue({
+          ui: context.ui,
+          defaults: context.defaults
+        }));
+      }
+    }
+    return {
+      layers,
+      tokens: cloneSnapshotValue(current?.tokens ?? appConfig.selaras?.tokens),
+      mode: current?.mode ?? "root"
+    };
+  };
+}

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

@@ -0,0 +1,3 @@
+import type { ColorRole } from './color-registry.js';
+/** Resolves runtime JavaScript role values without emitting unresolved CSS variables. */
+export declare function resolveRegisteredColorRole(role: unknown, fallback: ColorRole): ColorRole;

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

@@ -0,0 +1,14 @@
+import { colorRoles } from "#build/selaras-color-roles.mjs";
+import { builtinColorNames } from "./color-registry.js";
+const registeredRoles = /* @__PURE__ */ new Set([...builtinColorNames, ...colorRoles]);
+const warnedRoles = /* @__PURE__ */ new Set();
+export function resolveRegisteredColorRole(role, fallback) {
+  if (typeof role !== "string" || !registeredRoles.has(role)) {
+    if (import.meta.dev && typeof role === "string" && !warnedRoles.has(role)) {
+      warnedRoles.add(role);
+      console.warn(`[selaras] Unknown color role "${role}". Falling back to "${fallback}".`);
+    }
+    return fallback;
+  }
+  return role;
+}

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

@@ -0,0 +1,19 @@
+import type { ColorModePair, ColorRecipe } from './color-registry.js';
+export interface SeedColorSurfaces {
+    light: string;
+    dark: string;
+}
+export interface SeedColorOptions {
+    /** Opaque sRGB surfaces used to derive and verify each mode. */
+    surfaces?: SeedColorSurfaces;
+}
+/**
+ * Preserves one opaque sRGB seed as the resting fill and derives a complete,
+ * opaque two-mode web ColorRecipe around it.
+ * Custom or unresolved surfaces require explicit recipes instead.
+ */
+export declare function defineColorFromSeed(seed: string, options?: SeedColorOptions): ColorModePair<ColorRecipe>;
+export declare const seedColorContrastTargets: {
+    readonly text: 4.5;
+    readonly nonText: 3;
+};

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

@@ -0,0 +1,207 @@
+import { defaultSeedSurfaces } from "../default-color-metadata.js";
+const textMinimum = 4.5;
+const nonTextMinimum = 3;
+const textGuard = 4.7;
+const nonTextGuard = 3.2;
+const black = [0, 0, 0];
+const white = [1, 1, 1];
+function invalid(message) {
+  throw new Error(`Invalid Selaras seed color: ${message}`);
+}
+function rgb(red, green, blue) {
+  return [red, green, blue];
+}
+function parseHex(value, label) {
+  if (typeof value !== "string" || !/^#[0-9a-f]{6}$/i.test(value))
+    invalid(`${label} must be an opaque six-digit sRGB hex color such as "#FD5E53".`);
+  return rgb(
+    Number.parseInt(value.slice(1, 3), 16) / 255,
+    Number.parseInt(value.slice(3, 5), 16) / 255,
+    Number.parseInt(value.slice(5, 7), 16) / 255
+  );
+}
+function gammaToLinear(value) {
+  return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+}
+function linearToGamma(value) {
+  return value <= 31308e-7 ? value * 12.92 : 1.055 * value ** (1 / 2.4) - 0.055;
+}
+function rgbToLab(rgb2) {
+  const [red, green, blue] = rgb2;
+  const r = gammaToLinear(red);
+  const g = gammaToLinear(green);
+  const b = gammaToLinear(blue);
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  return [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s
+  ];
+}
+function labToRgb([L, a, b]) {
+  const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  return [
+    linearToGamma(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
+    linearToGamma(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+    linearToGamma(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s)
+  ];
+}
+function labToLch([l, a, b]) {
+  const chroma = Math.hypot(a, b);
+  return [l, chroma, chroma < 1e-7 ? 0 : (Math.atan2(b, a) * 180 / Math.PI + 360) % 360];
+}
+function lchToLab([l, chroma, hue]) {
+  const radians = hue * Math.PI / 180;
+  return [l, chroma * Math.cos(radians), chroma * Math.sin(radians)];
+}
+function inGamut(rgb2) {
+  return rgb2.every((value) => value >= -1e-7 && value <= 1 + 1e-7);
+}
+function fitLch([lightness, chroma, hue]) {
+  let low = 0;
+  let high = chroma;
+  let result = labToRgb(lchToLab([lightness, 0, hue]));
+  for (let iteration = 0; iteration < 24; iteration++) {
+    const candidateChroma = (low + high) / 2;
+    const candidate = labToRgb(lchToLab([lightness, candidateChroma, hue]));
+    if (inGamut(candidate)) {
+      low = candidateChroma;
+      result = candidate;
+    } else {
+      high = candidateChroma;
+    }
+  }
+  return rgb(
+    Math.min(1, Math.max(0, result[0])),
+    Math.min(1, Math.max(0, result[1])),
+    Math.min(1, Math.max(0, result[2]))
+  );
+}
+function quantize(rgb2) {
+  return parseHex(toHex(rgb2), "derived color");
+}
+function toHex(rgb2) {
+  return `#${rgb2.map((value) => Math.round(value * 255).toString(16).padStart(2, "0")).join("")}`;
+}
+function luminance(rgb2) {
+  const [red, green, blue] = rgb2;
+  const r = gammaToLinear(red);
+  const g = gammaToLinear(green);
+  const b = gammaToLinear(blue);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function contrast(left, right) {
+  const leftLuminance = luminance(left);
+  const rightLuminance = luminance(right);
+  const lighter = Math.max(leftLuminance, rightLuminance);
+  const darker = Math.min(leftLuminance, rightLuminance);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function mixLab(left, right, amount) {
+  const source = rgbToLab(left);
+  const target = rgbToLab(right);
+  const mixed = labToRgb(rgb(
+    source[0] * (1 - amount) + target[0] * amount,
+    source[1] * (1 - amount) + target[1] * amount,
+    source[2] * (1 - amount) + target[2] * amount
+  ));
+  return rgb(
+    Math.min(1, Math.max(0, mixed[0])),
+    Math.min(1, Math.max(0, mixed[1])),
+    Math.min(1, Math.max(0, mixed[2]))
+  );
+}
+function findSeries(seed, direction, step, count, accepts, distinct = true) {
+  const [seedLightness, seedChroma, seedHue] = labToLch(rgbToLab(seed));
+  let best;
+  for (let index = 0; index <= 1e3; index++) {
+    const baseLightness = index / 1e3;
+    const lightnesses = Array.from({ length: count }, (_, state) => baseLightness + direction * step * state);
+    if (lightnesses.some((value) => value < 0 || value > 1))
+      continue;
+    const colors = lightnesses.map((lightness) => quantize(fitLch([lightness, seedChroma, seedHue])));
+    if (!colors.every(accepts) || distinct && new Set(colors.map(toHex)).size !== colors.length)
+      continue;
+    const cost = Math.abs(baseLightness - seedLightness);
+    if (!best || cost < best.cost)
+      best = { colors, cost };
+  }
+  if (!best)
+    throw new Error("no series satisfies the required contrast.");
+  return best;
+}
+function findStateSeries(seed, direction, step, count, accepts) {
+  for (const scale of [1, 0.75, 0.5, 0.25, 0.1]) {
+    try {
+      return { ...findSeries(seed, direction, step * scale, count, accepts), collapsed: false };
+    } catch {
+    }
+  }
+  return { ...findSeries(seed, direction, 0, count, accepts, false), collapsed: true };
+}
+function requireSeries(mode, family, create) {
+  try {
+    return create();
+  } catch {
+    invalid(`cannot derive the ${mode} ${family} family while preserving its contrast targets; provide an explicit defineColor() recipe.`);
+  }
+}
+function deriveFillStates(seed, foreground, mode) {
+  const preferredTarget = mode === "light" ? black : white;
+  const alternateTarget = preferredTarget === black ? white : black;
+  for (const target of [preferredTarget, alternateTarget]) {
+    for (const scale of [1, 0.75, 0.5, 0.25, 0.125, 0.0625, 0.03125]) {
+      const hover = quantize(mixLab(seed, target, 0.06 * scale));
+      const pressed = quantize(mixLab(seed, target, 0.12 * scale));
+      const colors = [seed, hover, pressed];
+      if (new Set(colors.map(toHex)).size === colors.length && colors.every((color) => contrast(color, foreground) >= textMinimum))
+        return [hover, pressed];
+    }
+  }
+  invalid(`cannot derive distinct ${mode} fill states while preserving readable content; provide an explicit defineColor() recipe.`);
+}
+function deriveMode(seed, surface, mode) {
+  const direction = contrast(white, surface) > contrast(black, surface) ? 1 : -1;
+  const foreground = contrast(seed, black) >= contrast(seed, white) ? black : white;
+  if (contrast(seed, foreground) < textMinimum)
+    invalid(`cannot preserve the ${mode} fill while deriving readable content; provide an explicit defineColor() recipe.`);
+  const [fillHover, fillPressed] = deriveFillStates(seed, foreground, mode);
+  const fillColor = seed;
+  const subtle = quantize(mixLab(surface, fillColor, 0.1));
+  const subtleHover = quantize(mixLab(surface, fillColor, 0.14));
+  const subtlePressed = quantize(mixLab(surface, fillColor, 0.18));
+  const text = requireSeries(mode, "text/subtle", () => findStateSeries(seed, direction, 0.03, 3, (color) => [surface, subtle, subtleHover, subtlePressed].every((background) => contrast(color, background) >= textGuard))).colors;
+  const border = requireSeries(mode, "border", () => findStateSeries(seed, direction, 0.02, 1, (color) => contrast(color, surface) >= nonTextGuard)).colors[0];
+  return {
+    fill: toHex(fillColor),
+    fillHover: toHex(fillHover),
+    fillPressed: toHex(fillPressed),
+    onFill: toHex(foreground),
+    indicator: toHex(border),
+    subtle: toHex(subtle),
+    subtleHover: toHex(subtleHover),
+    subtlePressed: toHex(subtlePressed),
+    onSubtle: toHex(text[0]),
+    text: toHex(text[0]),
+    textHover: toHex(text[1]),
+    textPressed: toHex(text[2]),
+    border: toHex(border),
+    focus: toHex(text[0])
+  };
+}
+export function defineColorFromSeed(seed, options = {}) {
+  const surfaces = options.surfaces ?? defaultSeedSurfaces;
+  const color = parseHex(seed, "seed");
+  return {
+    light: deriveMode(color, parseHex(surfaces.light, "surfaces.light"), "light"),
+    dark: deriveMode(color, parseHex(surfaces.dark, "surfaces.dark"), "dark")
+  };
+}
+export const seedColorContrastTargets = {
+  text: textMinimum,
+  nonText: nonTextMinimum
+};

package/dist/runtime/utils/select-contracts.d.ts

@@ -0,0 +1,101 @@
+import type { VariantProps } from 'tailwind-variants';
+import type { selectTheme, SelectThemeSlots } from '../theme/select.js';
+import type { ColorRole } from './color-registry.js';
+import type { UiProp } from './ui.js';
+export type SelectValue = string | number;
+export interface SelectGroup<Item extends object> {
+    label: string;
+    items: readonly Item[];
+}
+/** Infer options from the entry array before unwrapping one group level. */
+export type SelectEntryItem<Entry> = Entry extends SelectGroup<infer Item> ? Item : Entry;
+export type SelectEntryGroup<Entry> = Extract<Entry, SelectGroup<object>>;
+export type SelectIdentityKeys<Item> = {
+    [Key in keyof Item]-?: Item[Key] extends SelectValue ? Key : never;
+}[keyof Item] & string;
+export type SelectIdentity<Entry, Key extends string> = SelectEntryItem<Entry>[Key & keyof SelectEntryItem<Entry>] & SelectValue;
+export type SelectModel<Value, Multiple extends boolean> = Multiple extends true ? Value[] : Value | undefined;
+type ValidEntry<Entry, Key extends string> = Entry extends SelectGroup<infer Item> ? SelectGroup<Item & Record<Key, SelectValue>> : Entry & Record<Key, SelectValue>;
+export interface SelectResolvedOption<Entry, Key extends string = 'value'> {
+    value: SelectIdentity<Entry, Key>;
+    label: string;
+    disabled: boolean;
+    /** Undefined while a selected identity is absent from the current options. */
+    raw: SelectEntryItem<Entry> | undefined;
+}
+export interface SelectProps<Entry extends object = {
+    value: SelectValue;
+    label?: string;
+    disabled?: boolean;
+}, Key extends string = 'value', Multiple extends boolean = false> {
+    id?: string;
+    name?: string;
+    /** ID of an associated form outside the component's ancestors. */
+    form?: string;
+    items: readonly Entry[] & NoInfer<readonly ValidEntry<Entry, Key>[]>;
+    valueKey?: Key & SelectIdentityKeys<SelectEntryItem<Entry>>;
+    labelKey?: keyof SelectEntryItem<Entry> & string;
+    open?: boolean;
+    /** Initial uncontrolled open state. */
+    defaultOpen?: boolean;
+    modelValue?: NoInfer<SelectModel<SelectIdentity<Entry, Key>, Multiple>>;
+    /** Mount-captured selection/reset target, adapted to the current multiple mode. */
+    defaultValue?: NoInfer<SelectModel<SelectIdentity<Entry, Key>, Multiple>>;
+    /** Controlled parents must update selection shape and mode together. */
+    multiple?: Multiple;
+    searchable?: boolean;
+    virtualize?: boolean | {
+        estimateSize?: number;
+        overscan?: number;
+    };
+    displayMode?: 'comma' | 'chip';
+    maxChips?: number;
+    loading?: boolean;
+    placeholder?: string;
+    disabled?: boolean;
+    required?: boolean;
+    size?: VariantProps<typeof selectTheme>['size'];
+    invalid?: boolean;
+    /** The focus-ring color; the resting ring stays neutral. */
+    color?: ColorRole;
+    clearable?: boolean;
+    searchTerm?: string;
+    resetSearchTermOnBlur?: boolean;
+    resetSearchTermOnSelect?: boolean;
+    arrow?: boolean;
+    /**
+     * Opts into the control's accessible small-screen presentation. Select uses
+     * a centered modal; Autocomplete keeps its editable combobox in a wider
+     * nonmodal panel. The active presentation is chosen on open and held until
+     * close.
+     */
+    adaptive?: boolean;
+    ui?: UiProp<SelectThemeSlots>;
+}
+export interface SelectEmits<Entry extends object = {
+    value: SelectValue;
+}, Key extends string = 'value', Multiple extends boolean = false> {
+    'update:open': [value: boolean];
+    'update:modelValue': [value: SelectModel<SelectIdentity<Entry, Key>, Multiple>];
+    'update:searchTerm': [value: string];
+}
+export interface SelectSlots<Entry extends object, Key extends string = 'value'> {
+    'item'?: (props: {
+        item: SelectEntryItem<Entry>;
+    }) => any;
+    'group'?: (props: {
+        group: SelectEntryGroup<Entry>;
+    }) => any;
+    'value'?: (props: {
+        selected: SelectResolvedOption<Entry, Key> | undefined;
+    }) => any;
+    'header'?: () => any;
+    'footer'?: () => any;
+    'empty'?: () => any;
+    'empty-filter'?: () => any;
+    'filter-icon'?: () => any;
+    'clear-icon'?: () => any;
+    'loading-icon'?: () => any;
+    'dropdown-icon'?: () => any;
+}
+export {};

package/dist/runtime/utils/table-contracts.d.ts

@@ -0,0 +1,60 @@
+import type { RowData } from '@tanstack/vue-table';
+import type { TableColumnDef, TableColumnVisibilityState, TableExpandedState, TableGetRowId, TableRowSelectionState, TableSortingState } from '../composables/use-table.js';
+import type { TableThemeSlots } from '../theme/table.js';
+import type { ColorRole } from './color-registry.js';
+import type { UiProp } from './ui.js';
+export interface TableProps<TData extends RowData = RowData> {
+    data: TData[];
+    columns?: TableColumnDef<TData>[];
+    selectable?: boolean;
+    pageSize?: number;
+    loading?: boolean;
+    sorting?: TableSortingState;
+    defaultSorting?: TableSortingState;
+    rowSelection?: TableRowSelectionState;
+    globalFilter?: string;
+    pageIndex?: number;
+    size?: 'sm' | 'md' | 'lg';
+    /** The sortable-header focus ring and loading indicator accent. @default 'primary' */
+    color?: ColorRole;
+    gridlines?: boolean;
+    striped?: boolean;
+    expandable?: boolean;
+    expanded?: TableExpandedState;
+    columnVisibility?: TableColumnVisibilityState;
+    columnToggle?: boolean;
+    /** Enables vertical scroll with a sticky header, capped at this CSS height (e.g. '24rem'). */
+    scrollHeight?: string;
+    virtualize?: boolean | {
+        estimateSize?: number;
+        overscan?: number;
+    };
+    /** Opts out of the local sorted/filtered/paginated row models - set when `data` is already sorted/filtered/paginated server-side, so this table doesn't redundantly (and incorrectly) reprocess an already-server-processed slice. `sorting`/`globalFilter`/`pageIndex` still drive the UI and still emit their `update:*` events the same way - only the *local row model* is skipped, not the state itself. `manualPagination` also suppresses the built-in Pagination UI entirely (there's no way to know the real page count from a server-paginated slice) - bring your own `SPagination`, bound to your own server metadata, the same way this table already expects you to bring your own search input for `globalFilter`. */
+    manualSorting?: boolean;
+    manualFiltering?: boolean;
+    manualPagination?: boolean;
+    /** Returns the stable id used by selection and expansion state. Defaults to the row index. */
+    getRowId?: TableGetRowId<TData>;
+    /** Adds a class to a body row based on its own data - e.g. highlighting a flagged row. Called per row, not per render, so keep it cheap. */
+    rowClass?: (row: TData) => string | undefined;
+    /** Same as `rowClass`, for inline styles. */
+    rowStyle?: (row: TData) => Record<string, string> | undefined;
+    ui?: UiProp<TableThemeSlots>;
+}
+export interface TableEmits<TData extends RowData = RowData> {
+    'update:sorting': [value: TableSortingState];
+    'update:rowSelection': [value: TableRowSelectionState];
+    'update:globalFilter': [value: string];
+    'update:pageIndex': [value: number];
+    'update:expanded': [value: TableExpandedState];
+    'update:columnVisibility': [value: TableColumnVisibilityState];
+    'rowClick': [row: TData, event: MouseEvent];
+    'rowContextmenu': [row: TData, event: MouseEvent];
+}
+export interface TableSlots<TData extends RowData = RowData> {
+    default?: () => any;
+    empty?: () => any;
+    expanded?: (props: {
+        row: TData;
+    }) => any;
+}

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

@@ -51,7 +51,7 @@ export declare function applyClassPrefix(classString: string, prefix?: string):
  * applies this to a `:ui` override *before* handing it to the slot function,
  * because `tailwind-merge` (bundled by `tailwind-variants`) has no concept
  * of Tailwind v4's `tw:`-style prefix syntax: a mixed merge - an unprefixed
- * base class (`bg-[var(--ui-primary)]`) against an already-prefixed override
+ * base class (`bg-[var(--_selaras-color-fill)]`) against an already-prefixed override
  * (`tw:bg-red-500`, exactly what a consumer is documented to write once a
  * prefix is configured) - never dedupes, confirmed directly (both classes
  * survive as-is). Since Selaras's own safelist stylesheet loads after the
@@ -101,11 +101,23 @@ export declare function withFallthroughClass(fallthroughClass: string | undefine
  * component. Bind the result with a single `v-bind` (Vue's template compiler
  * rejects two bare v-bind spreads on the same element).
  */
-export declare function useRootProps<T extends AnySlotFn>(slotFn: () => T, override: () => UiSlotValue | undefined): ComputedRef<{
+export declare function useRootProps<T extends AnySlotFn>(slotFn: () => T, override: () => UiSlotValue | undefined, options?: {
+    exclude?: (key: string) => boolean;
+    includeClass?: boolean;
+}): ComputedRef<{
     [x: string]: unknown;
 }>;
 /**
- * Merges a component's global `app.config.ui.<key>` override, then any
+ * Returns fallthrough attributes selected for a component's real interactive
+ * element. Wrapped controls use this alongside useRootProps: layout and
+ * component classes stay on the root slot, while native attributes/listeners
+ * such as autocomplete and focus/blur reach the input itself.
+ */
+export declare function useFallthroughAttrs(select: (key: string) => boolean): ComputedRef<{
+    [k: string]: unknown;
+}>;
+/**
+ * Merges a component's global `app.config.selaras.ui.<key>` override, then any
  * ancestor STheme's scoped `ui.<key>` override, into its base `tv()`
  * theme - each layered via tv()'s own `extend` composition, so an
  * override only needs to name the slots it actually changes. Falls back
@@ -113,7 +125,7 @@ export declare function useRootProps<T extends AnySlotFn>(slotFn: () => T, overr
  */
 export declare function useComponentTheme<T extends (...args: any[]) => any>(key: string, base: T): ComputedRef<T>;
 /**
- * The nearest (chain-merged) STheme `props.<key>` override, if any - a
+ * The nearest (chain-merged) STheme `defaults.<key>` override, if any - a
  * component reads this as its own prop's fallback, one level below its
  * own explicit prop but above whatever hardcoded/tv() default it'd
  * otherwise use (`props.size ?? useThemeProps('button').value.size`),
@@ -121,4 +133,14 @@ export declare function useComponentTheme<T extends (...args: any[]) => any>(key
  * generically instead of each needing its own bespoke injection key.
  */
 export declare function useThemeProps(key: string): ComputedRef<Record<string, unknown>>;
+/** Returns the nearest explicit STheme DOM marker for portalled content roots. */
+export declare function useThemeScope(): ComputedRef<string | undefined>;
+/** Managed ownership follows Vue ancestry, including through Teleport. */
+export declare function useThemeBindings(): ComputedRef<{
+    'data-selaras-theme': string;
+    'data-selaras-mode': "root" | "light" | "dark";
+    style: {
+        colorScheme: "light" | "dark";
+    } | undefined;
+}>;
 export {};

package/dist/runtime/utils/ui.js

@@ -39,11 +39,24 @@ export function withFallthroughClass(fallthroughClass, override) {
   }
   return [fallthroughClass, override].filter(Boolean).join(" ") || void 0;
 }
-export function useRootProps(slotFn, override) {
+export function useRootProps(slotFn, override, options) {
   const { fallthroughClass, attrsWithoutClass } = useRootFallthrough();
+  const themeBindings = useThemeBindings();
+  const rootAttrs = computed(() => {
+    if (!options?.exclude)
+      return attrsWithoutClass.value;
+    return Object.fromEntries(Object.entries(attrsWithoutClass.value).filter(([key]) => !options.exclude(key)));
+  });
   return computed(() => mergeProps(
-    attrsWithoutClass.value,
-    resolveSlot(slotFn(), withFallthroughClass(fallthroughClass.value, override()))
+    themeBindings.value,
+    rootAttrs.value,
+    resolveSlot(slotFn(), withFallthroughClass(options?.includeClass === false ? void 0 : fallthroughClass.value, override()))
+  ));
+}
+export function useFallthroughAttrs(select) {
+  const attrs = useAttrs();
+  return computed(() => Object.fromEntries(
+    Object.entries(attrs).filter(([key]) => select(key))
   ));
 }
 function collectThemeChain(context, pick, key) {
@@ -60,7 +73,7 @@ export function useComponentTheme(key, base) {
   const themeContext = inject(THEME_INJECTION_KEY, void 0);
   return computed(() => {
     let result = base;
-    const globalOverride = appConfig.ui?.[key];
+    const globalOverride = themeContext?.value.replaceGlobal ? void 0 : appConfig.selaras?.ui?.[key];
     if (globalOverride)
       result = tv({ extend: result, ...globalOverride });
     for (const override of collectThemeChain(themeContext?.value, (c) => c.ui, key))
@@ -69,6 +82,26 @@ export function useComponentTheme(key, base) {
   });
 }
 export function useThemeProps(key) {
+  const appConfig = useAppConfig();
   const themeContext = inject(THEME_INJECTION_KEY, void 0);
-  return computed(() => Object.assign({}, ...collectThemeChain(themeContext?.value, (c) => c.props, key)));
+  return computed(() => Object.assign(
+    {},
+    themeContext?.value.replaceGlobal ? void 0 : appConfig.selaras?.defaults?.[key],
+    ...collectThemeChain(themeContext?.value, (c) => c.defaults, key)
+  ));
+}
+export function useThemeScope() {
+  const themeContext = inject(THEME_INJECTION_KEY, void 0);
+  return computed(() => themeContext?.value.scopeId);
+}
+export function useThemeBindings() {
+  const context = inject(THEME_INJECTION_KEY, void 0);
+  return computed(() => {
+    const mode = context?.value.mode ?? "root";
+    return {
+      "data-selaras-theme": context?.value.scopeId ?? "global",
+      "data-selaras-mode": mode,
+      "style": mode === "root" ? void 0 : { colorScheme: mode }
+    };
+  });
 }