@viraui/react 0.0.1

package/dist/avatar/avatar.guide.json

@@ -0,0 +1,20 @@
+{
+  "name": "Avatar",
+  "summary": "Circular identity image or fallback for users, entities, or profile chips.",
+  "whenToUse": [
+    "Show a user or entity photo with text or image fallback",
+    "Display profile chips from x-small through big sizes",
+    "Defer image paint with a loading skeleton placeholder"
+  ],
+  "whenNotToUse": ["Interactive controls or navigation", "Non-identity imagery without a fallback plan"],
+  "accessibility": [
+    "Provide meaningful alt text when the image conveys identity",
+    "Use fallback text or initials when the image is unavailable",
+    "Loading uses aria-busy on the avatar region while Skeleton stays decorative"
+  ],
+  "antiPatterns": [
+    "Relying on Avatar children for layout sizing",
+    "Omitting meaningful alt text when the image conveys identity"
+  ],
+  "related": ["Skeleton"]
+}

package/dist/button/button.guide.json

@@ -0,0 +1,20 @@
+{
+  "name": "Button",
+  "summary": "Primary action control with size, variant, optional icon, and loading state.",
+  "whenToUse": [
+    "Labeled actions with text and optional leading or trailing icon",
+    "Primary, secondary, flat, or destructive visual treatments",
+    "Async actions that need a stable width while loading"
+  ],
+  "whenNotToUse": ["Icon-only actions without a visible label — use IconButton", "Navigation or non-button semantics"],
+  "accessibility": [
+    "Visible button text should name the action; avoid relying on icon alone",
+    "Loading sets aria-busy on the control while Spinner stays decorative",
+    "Disabled and loading states should not remove the action from the tab order without clear context"
+  ],
+  "antiPatterns": [
+    "Using Button without children as icon-only — prefer IconButton",
+    "Duplicating icon size on every icon slot — Button CSS sizes SVG descendants"
+  ],
+  "related": ["IconButton", "Icon", "Spinner"]
+}

package/dist/catalog.json

@@ -0,0 +1,110 @@
+{
+  "version": 1,
+  "package": "@viraui/react",
+  "components": [
+    {
+      "id": "avatar",
+      "name": "Avatar",
+      "summary": "Circular identity image or fallback for users, entities, or profile chips.",
+      "guidePath": "./avatar/avatar.guide.json"
+    },
+    {
+      "id": "clamp-text",
+      "name": "ClampText",
+      "summary": "Presentational utility that truncates overflowing copy to a fixed line count.",
+      "guidePath": "./clamp-text/clamp-text.guide.json"
+    },
+    {
+      "id": "elevator",
+      "name": "Elevator",
+      "summary": "No-DOM elevation utility that merges shadow hooks onto valid element children.",
+      "guidePath": "./elevator/elevator.guide.json"
+    },
+    {
+      "id": "button",
+      "name": "Button",
+      "summary": "Primary action control with size, variant, optional icon, and loading state.",
+      "guidePath": "./button/button.guide.json"
+    },
+    {
+      "id": "icon-button",
+      "name": "IconButton",
+      "summary": "Icon-only button that requires an accessible name through aria-label or aria-labelledby.",
+      "guidePath": "./icon-button/icon-button.guide.json"
+    },
+    {
+      "id": "textfield",
+      "name": "Textfield",
+      "summary": "Single-line field input with control-group chrome and optional addons.",
+      "guidePath": "./textfield/textfield.guide.json"
+    },
+    {
+      "id": "textarea",
+      "name": "Textarea",
+      "summary": "Multi-line field control with shared field copy and optional resize.",
+      "guidePath": "./textarea/textarea.guide.json"
+    },
+    {
+      "id": "slider",
+      "name": "Slider",
+      "summary": "Field-wrapped range input supporting single-thumb or two-thumb range selection.",
+      "guidePath": "./slider/slider.guide.json"
+    },
+    {
+      "id": "switch",
+      "name": "Switch",
+      "summary": "Field-wrapped toggle control with regular or small track and optional field copy.",
+      "guidePath": "./switch/switch.guide.json"
+    },
+    {
+      "id": "select",
+      "name": "Select",
+      "summary": "Field-wrapped single-select dropdown with grouped options and field copy.",
+      "guidePath": "./select/select.guide.json"
+    },
+    {
+      "id": "icon",
+      "name": "Icon",
+      "summary": "Decorative Vira SVG icon selected by name and variant.",
+      "guidePath": "./icon/icon.guide.json"
+    },
+    {
+      "id": "skeleton",
+      "name": "Skeleton",
+      "summary": "Decorative loading placeholder sized by props, not children.",
+      "guidePath": "./skeleton/skeleton.guide.json"
+    },
+    {
+      "id": "stack",
+      "name": "Stack",
+      "summary": "Flex layout primitive for arranging children with token spacing, alignment, and padding.",
+      "guidePath": "./stack/stack.guide.json"
+    },
+    {
+      "id": "surface",
+      "name": "Surface",
+      "summary": "Presentational container with token background, optional border, radius, and padding.",
+      "guidePath": "./surface/surface.guide.json"
+    },
+    {
+      "id": "spinner",
+      "name": "Spinner",
+      "summary": "Decorative SVG pulsing loading indicator used inside interactive components.",
+      "guidePath": "./spinner/spinner.guide.json"
+    },
+    {
+      "id": "text",
+      "name": "Text",
+      "summary": "Theme-aware body-copy primitive with tone, family, and responsive body sizing.",
+      "guidePath": "./text/text.guide.json"
+    },
+    {
+      "id": "title",
+      "name": "Title",
+      "summary": "Theme-aware heading and display typography primitive.",
+      "guidePath": "./title/title.guide.json"
+    }
+  ],
+  "consumption": "./consumption.json",
+  "themeSurface": "./theme-surface.json"
+}

package/dist/clamp-text/clamp-text.guide.json

@@ -0,0 +1,23 @@
+{
+  "name": "ClampText",
+  "summary": "Presentational utility that truncates overflowing copy to a fixed line count.",
+  "whenToUse": [
+    "Single- or multi-line ellipsis in constrained layouts",
+    "Clamp Text or Title roots through render",
+    "Inline or block clamped typography"
+  ],
+  "whenNotToUse": [
+    "Full text must remain visible without truncation",
+    "Heading semantics without composing Title through render"
+  ],
+  "accessibility": [
+    "Truncation hides content — provide full text nearby, in a tooltip, or on a detail view when it matters",
+    "Do not use clamped text alone for critical instructions or legal copy",
+    "Choose Title render for headings so document outline stays correct"
+  ],
+  "antiPatterns": [
+    "Using ClampText as a heading primitive without Title render",
+    "Expecting children-driven sizing instead of rows"
+  ],
+  "related": ["Text", "Title"]
+}

package/dist/components/avatar/avatar.css

@@ -0,0 +1,55 @@
+@scope (.Avatar) {
+  :scope {
+    --avatar-size: var(--space-2x-large);
+    --avatar-background: var(--global-contrast);
+    --avatar-foreground: var(--global-foreground);
+
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: var(--avatar-size);
+    block-size: var(--avatar-size);
+    min-inline-size: var(--avatar-size);
+    min-block-size: var(--avatar-size);
+    overflow: hidden;
+    border-radius: var(--radius-infinite);
+    background: var(--avatar-background);
+    color: var(--avatar-foreground);
+    vertical-align: middle;
+    -webkit-user-select: none;
+    user-select: none;
+    container-name: viraui-avatar;
+    container-type: inline-size;
+
+    &[data-size='x-small'] {
+      --avatar-size: var(--space-large);
+    }
+
+    &[data-size='small'] {
+      --avatar-size: var(--space-2x-large);
+    }
+
+    &[data-size='regular'] {
+      --avatar-size: var(--space-wide);
+    }
+
+    &[data-size='big'] {
+      --avatar-size: var(--space-2x-wide);
+    }
+
+    > .Image,
+    > .SkeletonPlaceholder {
+      inline-size: 100%;
+      block-size: 100%;
+    }
+
+    > .Image {
+      display: block;
+      object-fit: cover;
+    }
+
+    > .Label {
+      font-size: 30cqw;
+    }
+  }
+}

package/dist/components/avatar/avatar.d.ts

@@ -0,0 +1,50 @@
+import type { IntrinsicViraProps } from '@react/src/core/props/intrinsic-vira-props';
+import type * as React from 'react';
+import './avatar.css';
+/**
+ * Public Avatar props.
+ *
+ * Includes standard `span` attributes such as `id`, `title`, ARIA props, and event handlers,
+ * plus Vira-owned image, fallback, size, and loading controls.
+ *
+ * @default Native span pass-through props keep React defaults.
+ */
+export type AvatarProps = React.ComponentPropsWithoutRef<'span'> & IntrinsicViraProps & {
+    /**
+     * Supplies the avatar image source URL.
+     *
+     * @default No default; when omitted the fallback renders.
+     */
+    src?: string;
+    /**
+     * Supplies alternative text for the avatar image.
+     *
+     * @default ''
+     */
+    alt?: string;
+    /**
+     * Supplies the content shown when the image is absent or fails to load.
+     *
+     * @default No default; consumer must provide a value.
+     */
+    fallback: React.ReactNode;
+    /**
+     * Selects the rendered avatar footprint.
+     *
+     * @default 'small'
+     */
+    size?: 'x-small' | 'small' | 'regular' | 'big';
+    /**
+     * Replaces the avatar content with a same-size skeleton while image data is still loading upstream.
+     *
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * Ref forwarded to the rendered avatar root element.
+     *
+     * @default No ref is attached.
+     */
+    ref?: React.Ref<HTMLSpanElement>;
+};
+export declare const Avatar: React.FC<AvatarProps>;

package/dist/components/avatar/avatar.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Avatar as PrimitiveAvatar } from '@base-ui/react/avatar';
+import { Skeleton, Text } from '@react/src/components';
+import { extractIntrinsicViraProps } from '@react/src/core/props/intrinsic-vira-props';
+import { clsx } from 'clsx';
+import './avatar.css';
+const fallbackTextSizeByAvatarSize = {
+    'x-small': 'x-small',
+    small: 'x-small',
+    regular: 'small',
+    big: 'large',
+};
+export const Avatar = ({ alt = '', className, fallback, loading = false, ref, size = 'small', src, ...otherProps }) => {
+    const { componentProps, intrinsicAttributes } = extractIntrinsicViraProps(otherProps);
+    const hasImage = Boolean(src);
+    return (_jsx(PrimitiveAvatar.Root, { ...componentProps, ...intrinsicAttributes, ref: ref, "aria-busy": loading || undefined, className: clsx('Avatar', className), "data-has-image": hasImage ? 'true' : 'false', "data-loading": loading ? 'true' : 'false', "data-size": size, children: loading ? (_jsx(Skeleton, { minHeight: "100%", minWidth: "100%", radius: "infinite", width: "100%" })) : (_jsxs(_Fragment, { children: [hasImage ? (_jsx(PrimitiveAvatar.Image, { draggable: false, decoding: "async", loading: "eager", alt: alt, className: "Image", src: src })) : null, _jsx(PrimitiveAvatar.Fallback, { render: _jsx(Text, { className: "Label", whiteSpace: "nowrap", weight: "semibold", size: fallbackTextSizeByAvatarSize[size] }), children: fallback })] })) }));
+};

package/dist/components/avatar/index.d.ts

@@ -0,0 +1,2 @@
+export { Avatar } from './avatar';
+export type { AvatarProps } from './avatar';

package/dist/components/avatar/index.js

@@ -0,0 +1 @@
+export { Avatar } from './avatar';

package/dist/components/basic-input/basic-input.css

@@ -0,0 +1,45 @@
+@scope (.BasicInput) {
+  :scope {
+    --basic-input-background: var(--base-1);
+    --basic-input-color: var(--global-foreground);
+    --basic-input-placeholder-color: var(--global-disabled-foreground);
+    --basic-input-padding-inline: var(--space-small);
+    --basic-input-font-size: var(--font-scale-body-small);
+    --basic-input-border-radius: var(--radius-small);
+
+    box-sizing: border-box;
+    margin: 0;
+    inline-size: 100%;
+    min-inline-size: 0;
+    padding-inline: calc(var(--basic-input-padding-inline) + ((var(--basic-input-border-radius) + 0px) / 4));
+    font-family: inherit;
+    font-size: var(--basic-input-font-size);
+    font-variation-settings: 'wght' 400;
+    color: var(--basic-input-color);
+    background: var(--basic-input-background);
+    border: none;
+    border-radius: var(--basic-input-border-radius);
+    appearance: none;
+
+    /* Safari contacts autofill affordance: match input text color */
+    &::-webkit-contacts-auto-fill-button {
+      background-color: var(--basic-input-color);
+    }
+
+    &::placeholder {
+      color: var(--basic-input-placeholder-color);
+    }
+
+    &:disabled {
+      --basic-input-background: var(--global-disabled-background);
+      --basic-input-color: var(--global-disabled-foreground);
+      --basic-input-placeholder-color: var(--global-disabled-foreground);
+
+      cursor: not-allowed;
+    }
+
+    &[data-invalid] {
+      outline-color: oklab(from var(--highlight-red) l a b / 0.3);
+    }
+  }
+}

package/dist/components/basic-input/basic-input.d.ts

@@ -0,0 +1,14 @@
+import { Field } from '@base-ui/react/field';
+import * as React from 'react';
+import './basic-input.css';
+/**
+ * Internal shared field control for Textfield and Textarea.
+ *
+ * Merges `BasicInput` and `Control` classes onto one field control surface.
+ * With `render={<Input />}` (Base UI input), renders `Input` only — it already wraps
+ * `Field.Control`. With `render={<textarea />}`, renders `Field.Control` + native textarea.
+ */
+export type BasicInputProps = Omit<Field.Control.Props, 'ref'> & {
+    ref?: React.Ref<HTMLElement> | undefined;
+};
+export declare const BasicInput: React.ForwardRefExoticComponent<Omit<BasicInputProps, "ref"> & React.RefAttributes<HTMLElement>>;

package/dist/components/basic-input/basic-input.js

@@ -0,0 +1,17 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Field } from '@base-ui/react/field';
+import { Input as PrimitiveInput } from '@base-ui/react/input';
+import { clsx } from 'clsx';
+import * as React from 'react';
+import './basic-input.css';
+function usesInputPrimitiveRender(render) {
+    return React.isValidElement(render) && render.type === PrimitiveInput;
+}
+export const BasicInput = React.forwardRef(function BasicInput({ className, render, ...props }, ref) {
+    const mergedClassName = clsx('BasicInput', className);
+    if (usesInputPrimitiveRender(render)) {
+        return _jsx(PrimitiveInput, { ref: ref, className: mergedClassName, ...props });
+    }
+    return _jsx(Field.Control, { ref: ref, className: mergedClassName, render: render, ...props });
+});

package/dist/components/basic-input/field-helper-copy.d.ts

@@ -0,0 +1,13 @@
+import type * as React from 'react';
+type FieldHelperCopyProps = {
+    description?: React.ReactNode;
+    error?: React.ReactNode;
+};
+/**
+ * Renders field helper copy in the shared `Description` slot via `Field.Validity`.
+ * Static `error` replaces `description` only while invalid and `error` is set.
+ * `description` stays visible when invalid if `error` is omitted.
+ * `validate` / native messages render through `Field.Error` when there is no `description`.
+ */
+export declare function FieldHelperCopy({ description, error }: FieldHelperCopyProps): React.JSX.Element;
+export {};

package/dist/components/basic-input/field-helper-copy.js

@@ -0,0 +1,25 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Field } from '@base-ui/react/field';
+import { Text } from '@react/src/components/text';
+/**
+ * Renders field helper copy in the shared `Description` slot via `Field.Validity`.
+ * Static `error` replaces `description` only while invalid and `error` is set.
+ * `description` stays visible when invalid if `error` is omitted.
+ * `validate` / native messages render through `Field.Error` when there is no `description`.
+ */
+export function FieldHelperCopy({ description, error }) {
+    return (_jsx(Field.Validity, { children: (validity) => {
+            const isInvalid = validity.validity.valid === false;
+            if (isInvalid && error) {
+                return (_jsx(Field.Error, { className: "Description", match: true, render: _jsx(Text, { size: "x-small", tone: "danger" }), children: error }));
+            }
+            if (description) {
+                return (_jsx(Field.Description, { className: "Description", render: _jsx(Text, { size: "x-small", tone: "muted" }), children: description }));
+            }
+            if (isInvalid) {
+                return _jsx(Field.Error, { className: "Description", render: _jsx(Text, { size: "x-small", tone: "danger" }) });
+            }
+            return null;
+        } }));
+}

package/dist/components/basic-input/index.d.ts

@@ -0,0 +1,2 @@
+export { BasicInput } from './basic-input';
+export type { BasicInputProps } from './basic-input';

package/dist/components/basic-input/index.js

@@ -0,0 +1 @@
+export { BasicInput } from './basic-input';

package/dist/components/basic-input/input-control-group.d.ts

@@ -0,0 +1,26 @@
+import type * as React from 'react';
+export type InputControlGroupProps = {
+    /**
+     * Optional content rendered before the control (for example a currency prefix).
+     *
+     * @default No start addon is rendered.
+     */
+    startAddon?: React.ReactNode;
+    /**
+     * Optional content rendered after the control (for example an action button).
+     *
+     * @default No end addon is rendered.
+     */
+    endAddon?: React.ReactNode;
+    /**
+     * The children of the control group.
+     *
+     * @required
+     */
+    children: React.ReactNode;
+};
+/**
+ * Internal flex wrapper for a field control plus optional start/end addons.
+ * Not exported from the package public surface.
+ */
+export declare const InputControlGroup: React.FC<InputControlGroupProps>;

package/dist/components/basic-input/input-control-group.js

@@ -0,0 +1,8 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Stack } from '@react/src/components';
+/**
+ * Internal flex wrapper for a field control plus optional start/end addons.
+ * Not exported from the package public surface.
+ */
+export const InputControlGroup = ({ children, endAddon, startAddon }) => (_jsxs(Stack, { className: "ControlGroup", direction: "row", fillChildren: false, vAlign: "stretch", children: [startAddon && (_jsx(Stack, { className: "Addon", "data-position": "start", fillChildren: false, hAlign: "center", hPadding: ['small', 'x-small'], inline: true, shrink: false, vAlign: "center", children: startAddon })), children, endAddon && (_jsx(Stack, { className: "Addon", "data-position": "end", fillChildren: false, hAlign: "center", hPadding: "x-small", inline: true, shrink: false, vAlign: "center", children: endAddon }))] }));

package/dist/components/button/button.css

@@ -0,0 +1,156 @@
+@scope (.Button) {
+  :scope {
+    --button-background: var(--global-primary);
+    --button-color: var(--base-1);
+    --button-height: var(--space-2x-large);
+    --button-padding-inline: var(--space-medium);
+    --button-padding-block: var(--space-small);
+    --button-spinner-color: currentColor;
+    --button-icon-size: 1em;
+
+    -webkit-touch-callout: none;
+    -webkit-user-select: none;
+    user-select: none;
+    margin: 0;
+    cursor: pointer;
+    font-family: inherit;
+    display: inline-flex;
+    align-items: center;
+    min-inline-size: min-content;
+    max-block-size: var(--button-height);
+    block-size: var(--button-height);
+    justify-content: center;
+    text-decoration: none;
+    white-space: nowrap;
+    appearance: button;
+    overflow: hidden;
+    position: relative;
+    padding: var(--button-padding-block) var(--button-padding-inline);
+    font-variation-settings: 'wght' 500;
+    gap: var(--space-small);
+    border: 1px solid transparent;
+    background: var(--button-background);
+    color: var(--button-color);
+    font-size: var(--font-scale-body-medium);
+    border-radius: var(--radius-small);
+    transition: translate var(--easing-elastic) var(--duration-instant);
+    background-clip: padding-box;
+    will-change: translate;
+
+    /* Pressed: nudge label/icon down when enabled */
+    &:not(:disabled):active {
+      translate: 0 1px;
+    }
+
+    &[data-size='medium'] {
+      --button-height: var(--space-x-large);
+      --button-padding-inline: var(--space-small);
+      --button-padding-block: var(--space-small);
+      --button-icon-size: 0.9em;
+      gap: var(--space-x-small);
+    }
+
+    &[data-size='small'] {
+      --button-height: var(--space-large);
+      --button-padding-inline: var(--space-small);
+      --button-padding-block: var(--space-x-small);
+      --button-icon-size: 0.9em;
+      gap: var(--space-x-small);
+      font-size: var(--font-scale-body-small);
+    }
+
+    &[data-variant='primary'] {
+      --button-background: var(--global-primary);
+      --button-color: contrast-color(var(--global-primary));
+    }
+
+    &[data-variant='secondary'] {
+      --button-background: var(--global-contrast);
+      --button-color: var(--base-6);
+      background-clip: unset;
+
+      &:hover {
+        --button-background: oklab(from var(--global-contrast) l a b / calc(alpha + 0.05));
+      }
+    }
+
+    &[data-variant='flat'] {
+      --button-background: transparent;
+      --button-color: var(--base-5);
+
+      &:hover {
+        --button-background: var(--base-1);
+        --button-color: var(--base-7);
+      }
+    }
+
+    &[data-variant='destructive'] {
+      --button-background: oklab(from var(--highlight-red) l a b / 20%);
+      --button-color: var(--highlight-red);
+
+      &:hover {
+        --button-background: oklab(from var(--highlight-red) l a b / 30%);
+      }
+    }
+
+    &[data-icon-position='start'] {
+      flex-direction: row;
+    }
+
+    &[data-icon-position='end'] {
+      flex-direction: row-reverse;
+    }
+
+    &[data-icon-only='true'] {
+      gap: 0;
+      padding-block: var(--button-padding-block);
+      padding-inline: var(--button-padding-block);
+      inline-size: var(--button-height);
+      min-inline-size: var(--button-height);
+      max-inline-size: var(--button-height);
+      aspect-ratio: 1 / 1;
+    }
+
+    /* Disabled: override variant/hover tokens; aria-disabled for non-native disabled buttons */
+    &:disabled,
+    &:disabled:hover,
+    &[aria-disabled='true'] {
+      --button-background: var(--global-disabled-background);
+      --button-color: var(--global-disabled-foreground);
+
+      cursor: not-allowed;
+      box-shadow: none;
+    }
+
+    &[data-loading='true'][data-disabled] {
+      pointer-events: none;
+      border: 0;
+      box-shadow: none;
+      --button-color: var(--base-7);
+    }
+
+    > .Content {
+      display: inline-grid;
+      place-items: center;
+
+      /* Loading: hide label/icon in Content while SpinnerOverlay stays visible */
+      &[data-loading='true'] {
+        opacity: 0;
+      }
+
+      &:first-child > svg {
+        block-size: var(--button-icon-size);
+        inline-size: var(--button-icon-size);
+        flex-shrink: 0;
+      }
+    }
+
+    > .SpinnerOverlay {
+      position: absolute;
+      inset: 0;
+      display: grid;
+      place-content: center;
+      pointer-events: none;
+    }
+  }
+}