@viraui/react 0.0.1

package/dist/components/title/title.css

@@ -0,0 +1,126 @@
+@scope (.Title) {
+  :scope {
+    /* --- fluid scale --- */
+    --title-scale-min-vw: 320;
+    --title-scale-max-vw: 1440;
+    --title-scale-progress: clamp(
+      0,
+      (100vw - calc(var(--title-scale-min-vw) * 1px)) /
+        calc((var(--title-scale-max-vw) - var(--title-scale-min-vw)) * 1px),
+      1
+    );
+
+    /* Default fallback ≈ h2 → h3 */
+    --title-font-size: calc(
+      var(--font-scale-h3) + (var(--font-scale-h2) - var(--font-scale-h3)) * var(--title-scale-progress)
+    );
+
+    /* --- typography --- */
+    --title-font-family: var(--font-family-heading);
+    --title-font-weight: 500;
+    --title-font-width: 100;
+    --title-font-opsz: 16;
+    --title-line-height: var(--font-leading-standard);
+    --title-letter-spacing: -0.03em;
+
+    /* --- layout defaults --- */
+    --title-align: start;
+    --title-max-width: none;
+    --title-white-space: normal;
+    --title-padding-inline-start: 0;
+    --title-padding-inline-end: 0;
+    --title-padding-block-start: 0;
+    --title-padding-block-end: 0;
+
+    margin: 0;
+    max-inline-size: var(--title-max-width);
+    font-family: var(--title-font-family);
+    font-size: var(--title-font-size);
+    line-height: var(--title-line-height);
+    letter-spacing: var(--title-letter-spacing);
+    text-align: var(--title-align);
+    white-space: var(--title-white-space);
+    word-break: break-word;
+    font-optical-sizing: auto;
+    font-variation-settings:
+      'wght' var(--title-font-weight),
+      'wdth' var(--title-font-width),
+      'opsz' var(--title-font-opsz);
+    text-box: var(--title-trim) var(--title-trim-type);
+
+    &[data-title-balanced='true'] {
+      text-wrap: balance;
+    }
+
+    &[data-title-has-padding='true'] {
+      padding: var(--title-padding-block-start) var(--title-padding-inline-end) var(--title-padding-block-end)
+        var(--title-padding-inline-start);
+    }
+
+    /* --- level overrides --- */
+    &[data-title-level='display'] {
+      --title-font-size: calc(
+        var(--font-scale-h1) + (var(--font-scale-display) - var(--font-scale-h1)) * var(--title-scale-progress)
+      );
+    }
+
+    &[data-title-level='h1'] {
+      --title-font-size: calc(
+        var(--font-scale-h2) + (var(--font-scale-h1) - var(--font-scale-h2)) * var(--title-scale-progress)
+      );
+    }
+
+    &[data-title-level='h2'] {
+      --title-font-size: calc(
+        var(--font-scale-h3) + (var(--font-scale-h2) - var(--font-scale-h3)) * var(--title-scale-progress)
+      );
+    }
+
+    &[data-title-level='h3'] {
+      --title-font-size: calc(
+        var(--font-scale-h4) + (var(--font-scale-h3) - var(--font-scale-h4)) * var(--title-scale-progress)
+      );
+    }
+
+    &[data-title-level='h4'] {
+      --title-font-size: calc(
+        var(--font-scale-h5) + (var(--font-scale-h4) - var(--font-scale-h5)) * var(--title-scale-progress)
+      );
+    }
+
+    &[data-title-level='h5'] {
+      --title-font-size: calc(
+        var(--font-scale-h6) + (var(--font-scale-h5) - var(--font-scale-h6)) * var(--title-scale-progress)
+      );
+      --title-letter-spacing: -0.02em;
+    }
+
+    &[data-title-level='h6'] {
+      --title-font-size: calc(
+        var(--font-scale-body-medium) + (var(--font-scale-h6) - var(--font-scale-body-medium)) *
+          var(--title-scale-progress)
+      );
+      --title-letter-spacing: -0.02em;
+    }
+
+    &[data-title-has-literal-color='true'] {
+      color: var(--title-literal-color);
+    }
+
+    &[data-title-line-height='none'] {
+      --title-line-height: 0;
+    }
+
+    &[data-title-line-height='x-small'] {
+      --title-line-height: var(--font-leading-x-small);
+    }
+
+    &[data-title-line-height='small'] {
+      --title-line-height: var(--font-leading-small);
+    }
+
+    &[data-title-line-height='large'] {
+      --title-line-height: var(--font-leading-large);
+    }
+  }
+}

package/dist/components/title/title.d.ts

@@ -0,0 +1,117 @@
+import { useRender } from '@base-ui/react/use-render';
+import type { ThemeTypes } from '@foundation/platforms/web/vira/types';
+import type * as React from 'react';
+import './title.css';
+import type { IntrinsicViraProps } from '@react/src/core/props/intrinsic-vira-props';
+type TitleSpace = ThemeTypes['space'];
+type TitleAxisPadding = TitleSpace | [TitleSpace | 0, TitleSpace | 0];
+/**
+ * Public Title props.
+ *
+ * Includes standard text and heading HTML attributes such as `children`, `id`, `title`, and event handlers,
+ * plus Vira-owned heading typography, color, and layout controls.
+ *
+ * @default Base HTML pass-through props keep upstream defaults.
+ */
+export type TitleProps = React.ComponentPropsWithoutRef<'span'> & IntrinsicViraProps & {
+    /**
+     * Replaces the default `span` root using Base UI render semantics.
+     *
+     * @default The title renders a `span` root.
+     */
+    render?: useRender.RenderProp;
+    /**
+     * Ref forwarded to the rendered title root element.
+     *
+     * @default No ref is attached.
+     */
+    ref?: React.Ref<HTMLElement>;
+    /**
+     * Selects a semantic heading typography size from the active theme scale.
+     *
+     * This controls only the visual preset. Semantic heading choice remains owned by `render`.
+     *
+     * @default 'h1'
+     */
+    level?: 'display' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+    /**
+     * Overrides the level preset weight when a custom variable-font value is needed.
+     *
+     * @default No weight override.
+     */
+    weight?: number;
+    /**
+     * Applies a literal color escape hatch.
+     *
+     * @default No literal color override.
+     */
+    color?: string;
+    /**
+     * Controls line height through foundation leading tokens.
+     *
+     * @default 'standard'
+     */
+    lineHeight?: 'none' | 'x-small' | 'small' | 'standard' | 'large';
+    /**
+     * Aligns text using logical alignment values.
+     *
+     * @default 'start'
+     */
+    align?: React.CSSProperties['textAlign'];
+    /**
+     * Constrains the maximum inline size of the rendered text block.
+     *
+     * @default No max width constraint.
+     */
+    maxWidth?: string;
+    /**
+     * Controls white-space preservation and wrapping behavior.
+     *
+     * @default 'normal'
+     */
+    whiteSpace?: React.CSSProperties['whiteSpace'];
+    /**
+     * Enables balanced wrapping for block-like titles.
+     *
+     * @default false
+     */
+    balanced?: boolean;
+    /**
+     * Sets inline padding using one token for both sides or a `[start, end]` tuple.
+     *
+     * @default No inline padding.
+     */
+    hPadding?: TitleAxisPadding;
+    /**
+     * Sets block padding using one token for both sides or a `[start, end]` tuple.
+     *
+     * @default No block padding.
+     */
+    vPadding?: TitleAxisPadding;
+    /**
+     * Trims text box whitespace at the chosen edge when the browser supports `text-box`.
+     *
+     * @default 'both'
+     */
+    trim?: 'start' | 'end' | 'both';
+    /**
+     * Selects the `text-box` trim basis when `trim` is active.
+     *
+     * @default 'cap alphabetic'
+     */
+    trimType?: string;
+    /**
+     * Overrides the variable-font width axis when the active font supports it.
+     *
+     * @default No width override.
+     */
+    fontWidth?: number;
+    /**
+     * Overrides the variable-font optical size axis when the active font supports it.
+     *
+     * @default No optical size override.
+     */
+    opticalSize?: number;
+};
+export declare const Title: React.FC<TitleProps>;
+export {};

package/dist/components/title/title.js

@@ -0,0 +1,41 @@
+'use client';
+import { useRender } from '@base-ui/react/use-render';
+import { extractIntrinsicViraProps } from '@react/src/core/props/intrinsic-vira-props';
+import { resolveAxisPadding } from '@react/src/core/styles/resolve-axis-padding';
+import { clsx } from 'clsx';
+import './title.css';
+export const Title = ({ align = 'start', balanced = false, className, color, fontWidth, hPadding, level = 'h1', lineHeight = 'standard', maxWidth, opticalSize, ref, render, style, trim = 'both', trimType = 'cap alphabetic', vPadding, weight, whiteSpace = 'normal', ...otherProps }) => {
+    const hasPadding = Boolean(hPadding || vPadding);
+    const { componentProps, intrinsicAttributes } = extractIntrinsicViraProps(otherProps);
+    const dynamicStyle = {
+        '--title-align': align,
+        '--title-max-width': maxWidth ?? 'none',
+        '--title-literal-color': color,
+        '--title-white-space': whiteSpace,
+        '--title-trim': trim ? `trim-${trim}` : 'initial',
+        '--title-trim-type': trim ? trimType : 'initial',
+        ...(typeof weight === 'number' ? { '--title-font-weight': weight } : {}),
+        ...(fontWidth !== undefined ? { '--title-font-width': fontWidth } : {}),
+        ...(opticalSize !== undefined ? { '--title-font-opsz': opticalSize } : {}),
+        ...resolveAxisPadding(hPadding, '--title-padding-inline-start', '--title-padding-inline-end'),
+        ...resolveAxisPadding(vPadding, '--title-padding-block-start', '--title-padding-block-end'),
+        ...style,
+    };
+    return useRender({
+        defaultTagName: 'span',
+        render,
+        ref,
+        props: {
+            ...componentProps,
+            ...intrinsicAttributes,
+            'data-title-level': level,
+            'data-title-weight': weight !== undefined ? 'custom' : 'preset',
+            'data-title-line-height': lineHeight,
+            'data-title-balanced': balanced ? 'true' : 'false',
+            'data-title-has-padding': hasPadding ? 'true' : 'false',
+            'data-title-has-literal-color': color ? 'true' : 'false',
+            className: clsx('Title', className),
+            style: dynamicStyle,
+        },
+    });
+};

package/dist/core/elevation/elevation-types.d.ts

@@ -0,0 +1,17 @@
+/** Resting elevation level backed by preflight `elevations.css`. */
+export type ElevationLevel = 0 | 1 | 2 | 3 | 4;
+/** Shadow cast axis backed by preflight `elevations.css`. */
+export type ElevationDirection = 'right' | 'left' | 'top' | 'bottom';
+/** CSS color value for the `--shadow-color` custom property. */
+export type ElevationShadowColor = string;
+export declare const ELEVATION_DEFAULTS: {
+    readonly direction: "bottom";
+    readonly shadowColor: "oklch(0% 0 0)";
+};
+export type ElevationConfig = {
+    resting: ElevationLevel;
+    hover?: ElevationLevel;
+    direction?: ElevationDirection;
+    shadowColor?: ElevationShadowColor;
+    extraShadow?: string;
+};

package/dist/core/elevation/elevation-types.js

@@ -0,0 +1,4 @@
+export const ELEVATION_DEFAULTS = {
+    direction: 'bottom',
+    shadowColor: 'oklch(0% 0 0)',
+};

package/dist/core/elevation/get-elevation-props.d.ts

@@ -0,0 +1,12 @@
+import type * as React from 'react';
+import { type ElevationConfig, type ElevationDirection, type ElevationLevel } from './elevation-types';
+export type ElevationAttributes = {
+    'data-elevation': ElevationLevel;
+    'data-elevation-direction': ElevationDirection;
+    'data-elevation-hover'?: ElevationLevel;
+};
+export type ElevationPropsResult = {
+    attributes: ElevationAttributes;
+    style: React.CSSProperties;
+};
+export declare const getElevationProps: ({ resting, hover, direction, shadowColor, extraShadow, }: ElevationConfig) => ElevationPropsResult;

package/dist/core/elevation/get-elevation-props.js

@@ -0,0 +1,12 @@
+import { ELEVATION_DEFAULTS, } from './elevation-types';
+export const getElevationProps = ({ resting, hover, direction = ELEVATION_DEFAULTS.direction, shadowColor = ELEVATION_DEFAULTS.shadowColor, extraShadow, }) => ({
+    attributes: {
+        'data-elevation': resting,
+        'data-elevation-direction': direction,
+        ...(hover !== undefined ? { 'data-elevation-hover': hover } : {}),
+    },
+    style: {
+        '--shadow-color': shadowColor,
+        ...(extraShadow !== undefined ? { '--extra-shadow': extraShadow } : {}),
+    },
+});

package/dist/core/props/intrinsic-vira-props.d.ts

@@ -0,0 +1,23 @@
+export type IntrinsicViraProps = {
+    /**
+     * Adds `data-grow="false"` to the component root when false.
+     *
+     * @default The component root does not render a grow attribute.
+     */
+    grow?: boolean | undefined;
+    /**
+     * Adds `data-shrink="false"` to the component root when false.
+     *
+     * @default The component root does not render a shrink attribute.
+     */
+    shrink?: boolean | undefined;
+};
+type IntrinsicViraAttributes = {
+    'data-grow'?: 'false';
+    'data-shrink'?: 'false';
+};
+export declare const extractIntrinsicViraProps: <Props extends IntrinsicViraProps>(props: Props) => {
+    componentProps: Omit<Props, keyof IntrinsicViraProps>;
+    intrinsicAttributes: IntrinsicViraAttributes;
+};
+export {};

package/dist/core/props/intrinsic-vira-props.js

@@ -0,0 +1,10 @@
+export const extractIntrinsicViraProps = (props) => {
+    const { grow, shrink, ...componentProps } = props;
+    return {
+        componentProps,
+        intrinsicAttributes: {
+            ...(grow === false ? { 'data-grow': 'false' } : {}),
+            ...(shrink === false ? { 'data-shrink': 'false' } : {}),
+        },
+    };
+};

package/dist/core/styles/resolve-axis-padding.d.ts

@@ -0,0 +1,5 @@
+import type { ThemeTypes } from '@foundation/platforms/web/vira/types';
+import type * as React from 'react';
+type AxisPadding = ThemeTypes['space'] | [ThemeTypes['space'] | 0, ThemeTypes['space'] | 0];
+export declare const resolveAxisPadding: (value: AxisPadding | undefined, startKey: string, endKey: string) => React.CSSProperties;
+export {};

package/dist/core/styles/resolve-axis-padding.js

@@ -0,0 +1,17 @@
+import { resolveThemeValue } from '@react/src/core/theme/resolve-theme-value';
+export const resolveAxisPadding = (value, startKey, endKey) => {
+    if (!value) {
+        return {};
+    }
+    if (Array.isArray(value)) {
+        return {
+            [startKey]: resolveThemeValue(value[0], 'space', 0),
+            [endKey]: resolveThemeValue(value[1], 'space', 0),
+        };
+    }
+    const resolvedValue = resolveThemeValue(value, 'space', 0);
+    return {
+        [startKey]: resolvedValue,
+        [endKey]: resolvedValue,
+    };
+};

package/dist/core/theme/resolve-theme-value.d.ts

@@ -0,0 +1,5 @@
+import theme from '@foundation/platforms/web/vira/vira-nested.json';
+type ThemeTree = typeof theme;
+type ThemeKey = keyof ThemeTree;
+export declare const resolveThemeValue: <TKey extends ThemeKey, TValue extends keyof ThemeTree[TKey], TFallback>(key: TValue | null | undefined | 0, themeKey: TKey, fallbackValue: TFallback) => ThemeTree[TKey][TValue] | TFallback;
+export {};

package/dist/core/theme/resolve-theme-value.js

@@ -0,0 +1,7 @@
+import theme from '@foundation/platforms/web/vira/vira-nested.json';
+export const resolveThemeValue = (key, themeKey, fallbackValue) => {
+    if (!key) {
+        return fallbackValue;
+    }
+    return theme[themeKey][key];
+};

package/dist/elevator/elevator.guide.json

@@ -0,0 +1,23 @@
+{
+  "name": "Elevator",
+  "summary": "No-DOM elevation utility that merges shadow hooks onto valid element children.",
+  "whenToUse": [
+    "Apply resting and optional hover elevation to existing elements",
+    "Compose animated box-shadow transitions with data-elevation hooks",
+    "Use getElevationProps when you need the mapping directly"
+  ],
+  "whenNotToUse": [
+    "When you need a wrapper DOM node for layout or styling isolation",
+    "Non-element children that cannot receive merged props"
+  ],
+  "accessibility": [
+    "Elevation is visual only — do not use shadow depth as the only affordance for interactivity",
+    "Preserve child focus order and semantics; Elevator does not add a focusable node",
+    "Respect reduced-motion preferences when pairing animated elevation with motion"
+  ],
+  "antiPatterns": [
+    "Wrapping invalid or non-element nodes",
+    "Overwriting child transition shorthand without composing box-shadow"
+  ],
+  "related": ["Surface"]
+}

package/dist/guides/consumption.json

@@ -0,0 +1,44 @@
+{
+  "summary": "Minimal bootstrap for external apps consuming @viraui/react.",
+  "requiredPackages": {
+    "@viraui/react": "Public components, preflight CSS, and usage guides.",
+    "react": "Peer dependency.",
+    "react-dom": "Peer dependency.",
+    "@base-ui/react": "Peer dependency for wrapped primitives."
+  },
+  "optionalPackages": {
+    "@viraui/foundation": "Preset Vira brand theme CSS, ThemeTypes, and JSON only.",
+    "@viraui/icons": "ViraUI icons assets when not using Icon from @viraui/react."
+  },
+  "importOrder": [
+    "@viraui/react/preflight.css",
+    "Compatible theme CSS (preset @viraui/foundation/vira/css, custom theme CSS, or future theme-builder export)",
+    "Consumer @font-face rules matching theme font-family strings or import from fontsource packages"
+  ],
+  "themePaths": [
+    {
+      "id": "preset-vira",
+      "label": "Preset Vira brand",
+      "foundation": true,
+      "themeCss": "@viraui/foundation/vira/css"
+    },
+    {
+      "id": "custom",
+      "label": "Consumer custom theme",
+      "foundation": false,
+      "themeCss": "Consumer-authored CSS with public semantic variables"
+    },
+    {
+      "id": "theme-builder",
+      "label": "Future theme builder export",
+      "foundation": false,
+      "themeCss": "Exported theme CSS from a Vira theme builder"
+    }
+  ],
+  "discovery": {
+    "catalog": "@viraui/react/catalog.json",
+    "consumption": "@viraui/react/consumption.json",
+    "themeSurface": "@viraui/react/theme-surface.json",
+    "componentGuide": "@viraui/react/<component>.guide.json"
+  }
+}

package/dist/guides/theme-surface.json

@@ -0,0 +1,61 @@
+{
+  "summary": "Public semantic CSS custom properties required by @viraui/react components.",
+  "groups": [
+    {
+      "id": "base",
+      "pattern": "--base-*",
+      "purpose": "Semantic neutral ramp for surfaces and text on themed backgrounds."
+    },
+    {
+      "id": "global",
+      "pattern": "--global-*",
+      "purpose": "App-facing foreground, background, primary, muted, interactive, disabled, and contrast colors."
+    },
+    {
+      "id": "highlight",
+      "pattern": "--highlight-*",
+      "purpose": "Status and decorative highlight palette."
+    },
+    {
+      "id": "radius",
+      "pattern": "--radius-*",
+      "purpose": "Semantic radius scale for component chrome."
+    },
+    {
+      "id": "space",
+      "pattern": "--space-*",
+      "purpose": "Semantic spacing scale for layout and component padding."
+    },
+    {
+      "id": "font-scale",
+      "pattern": "--font-scale-*",
+      "purpose": "Semantic typography sizes including display, headings, and body steps."
+    },
+    {
+      "id": "font-family",
+      "pattern": "--font-family-heading | --font-family-body | --font-family-mono",
+      "purpose": "Semantic font-family touchpoints; consumers must provide matching @font-face rules."
+    },
+    {
+      "id": "font-leading",
+      "pattern": "--font-leading-*",
+      "purpose": "Semantic line-height scale for text and title components."
+    },
+    {
+      "id": "color-primitives",
+      "pattern": "--color-{palette}-{step}",
+      "purpose": "Raw palette steps referenced by semantic aliases; not the primary consumer override API."
+    },
+    {
+      "id": "breakpoint",
+      "pattern": "--breakpoint-*",
+      "purpose": "Theme-owned min-width tokens for responsive layout."
+    },
+    {
+      "id": "motion",
+      "pattern": "--duration-* | --easing-*",
+      "purpose": "Duration and easing tokens for component motion."
+    }
+  ],
+  "compatibilityRule": "Custom and builder-generated themes must keep documented semantic variable names stable while values may change."
+}

package/dist/icon/icon.guide.json

@@ -0,0 +1,23 @@
+{
+  "name": "Icon",
+  "summary": "Decorative Vira SVG icon selected by name and variant.",
+  "whenToUse": [
+    "Decorative glyphs inside buttons, fields, or labels",
+    "Named icons from the Vira icon set via name and variant",
+    "Passing icon slots to components that accept ReactNode icons"
+  ],
+  "whenNotToUse": [
+    "Standalone interactive controls — wrap in Button or IconButton",
+    "Meaningful icons without an accessible name on the parent control"
+  ],
+  "accessibility": [
+    "Icon is decorative by default (aria-hidden) — the parent control or label must convey meaning",
+    "Do not use Icon as the only accessible name for an action",
+    "When the glyph carries unique meaning, expose that meaning on the interactive parent"
+  ],
+  "antiPatterns": [
+    "Passing IconName strings into components that expect ReactNode icon slots",
+    "Using Icon as the only accessible name for an action"
+  ],
+  "related": ["Button", "IconButton"]
+}

package/dist/icon-button/icon-button.guide.json

@@ -0,0 +1,20 @@
+{
+  "name": "IconButton",
+  "summary": "Icon-only button that requires an accessible name through aria-label or aria-labelledby.",
+  "whenToUse": [
+    "Compact toolbar or chrome actions identified only by icon",
+    "Same size, variant, and loading model as Button without visible label",
+    "Decorative glyph with explicit accessible naming on the root button"
+  ],
+  "whenNotToUse": ["Actions that need visible text — use Button", "Missing both aria-label and aria-labelledby"],
+  "accessibility": [
+    "Provide aria-label or aria-labelledby on every IconButton — icon alone is not a name",
+    "Loading sets aria-busy on the control; Spinner is decorative",
+    "Keep the accessible name stable when loading state changes"
+  ],
+  "antiPatterns": [
+    "Passing children or iconPosition — not part of the public API",
+    "Using icon-only Button instead of IconButton"
+  ],
+  "related": ["Button", "Icon", "Spinner"]
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './components';
+export type { IntrinsicViraProps } from './core/props/intrinsic-vira-props';

package/dist/index.js

@@ -0,0 +1 @@
+export * from './components';