@inkra/react 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Inkra contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,214 @@
-# Temporary Holding Version
+# Inkra
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Inkra is a pencil-styled React component library. It includes action, form, overlay, navigation, content and feedback components, plus Calendar, DayAgenda, JourneyMap and deterministic drawing primitives. The first `0.1.0` release is being prepared; this package is still an unpublished candidate unless a corresponding registry release has been announced.
+
+Source and maintenance: [inkrajs/inkra](https://github.com/inkrajs/inkra).
+
+Package name: `@inkra/react`. Import the scoped package and its stylesheet;
+the unscoped `inkra` name is not this library's published package.
+
+## Installation
+
+The package is prepared for npm-compatible installation, but this repository does not assume that a release has been published. In a workspace, depend on the local package according to the workspace package manager's conventions.
+
+The manifest declares React 18 or newer as a peer dependency; release checks target React 18 and 19. ESM, TypeScript declarations, CSS and font assets are included. The release pipeline verifies SSR-to-browser hydration from the installed package, including form controls, portals, canvas recovery and the lazy-loaded map. Do not interpret the peer range as testing every future React version.
+
+Inkra components require a React client boundary. Next.js and React Server Components are not a certified integration in 0.1.0; do not import interactive components directly into a Server Component. React 18 development SSR of Calendar still reports a layout-effect warning from react-day-picker 9; its browser hydration is checked separately. Applications requiring warning-free React 18 SSR should mount Calendar after hydration. Server and client must use matching locale, dates, values and theme inputs.
+
+## Usage
+
+Import the component styles once near the application entry point:
+
+```tsx
+import '@inkra/react/styles.css';
+
+import { Button, ButtonGroup, ButtonLink, PencilLine, PencilSurface, PencilText } from '@inkra/react';
+
+export function Actions() {
+  return (
+    <>
+      <ButtonGroup aria-label="Document actions">
+        <Button variant="primary" size="md" seed="save-action">
+          Save changes
+        </Button>
+        <ButtonLink href="/preview" variant="outline">
+          Preview
+        </ButtonLink>
+      </ButtonGroup>
+      <div>
+        <PencilLine seed="section-divider" />
+        <PencilSurface variant="paper" seed="note-paper">
+          <PencilText seed="note-title">Project notes</PencilText>
+        </PencilSurface>
+      </div>
+    </>
+  );
+}
+```
+
+To use only the design tokens, import `@inkra/react/tokens.css` instead.
+
+## Button
+
+`Button` forwards its ref and native button attributes. Its default `type` is `button`, so placing it inside a form will not submit unexpectedly.
+
+```tsx
+<Button variant="secondary" size="sm" onClick={handleCancel}>
+  Cancel
+</Button>
+
+<Button loading seed="save-request">
+  Save
+</Button>
+```
+
+Supported Inkra props:
+
+- `variant`: `primary`, `secondary`, `outline`, `ghost`, `destructive`, or `link`
+- `size`: `xs`, `sm`, `md`, `lg`, `icon-xs`, `icon-sm`, `icon`, or `icon-lg`
+- `loading`: marks the button busy and disables interaction
+- `seed`: controls the deterministic hand-drawn decoration
+- `startIcon` / `endIcon`: preserve logical icon placement in LTR and RTL layouts
+
+All standard `button` props, including `disabled`, `name`, `value`, `form`, `aria-*`, and `data-*`, are passed to the native element.
+
+`ButtonLink` renders a native anchor with the same visual props. Disabled or loading links remove their `href`, leave the tab order, expose `aria-disabled`, and block primary, modified, auxiliary and keyboard navigation. `ButtonGroup` renders `role="group"` with horizontal or vertical layout; provide `aria-label` or `aria-labelledby`. Icon-only controls use a square visual size and require an accessible name.
+
+## Form Controls and Select
+
+`Input` defaults to an underline appearance, with explicit `outline`, `soft` and `ghost` variants. It supports `startIcon`, `endIcon`, `prefix`, `suffix`, `clearable`, `loading`, `startAction`, `endAction`, `fullWidth` and logical `textAlign`. Use `onValueChange` for edits and clearing; native `onChange` does not receive fabricated clear events. `Field` connects labels, descriptions and errors.
+
+`InputNumber` places decrease and increase buttons on either side of a centered numeric input, with no clear button. Keyboard deletion produces `null`; decimal stepping and out-of-range validation remain native. `Slider` supports single/range values, horizontal/vertical layout and `standard` or `inset` appearance.
+
+`Select.Root` uses string values for single selection and string arrays with `multiple`. Multi-select remains open while toggling items and submits repeated values under the same field name. `Select.Clear` is a separate button; never nest it inside the trigger.
+
+`Select.Trigger` supports `startIcon`, `endIcon`, `hideValue`, `hideIndicator`, `iconOnly`, `fullWidth` and `textAlign`. The existing `icon` prop replaces the dropdown indicator. Icon-only mode keeps a square hit target of at least 44px and retains selected text as an accessible description. Provide a Field/ARIA name and Tooltip for icon-only triggers. Decorative slots must not contain interactive controls.
+
+`Select.Searchable` is a separate combobox API accepting `items` with `value`, `label`, optional `disabled` and `keywords`. `searchPlacement="trigger"` uses an editable input; `"popup"` places search inside the popup. It supports single/multiple values, filtering and clear controls. The compound Trigger appearance props do not implicitly apply to this separate API.
+
+## Overlay Sections
+
+`Overlay.Content layout="sections"` composes a fixed `Header`, a scrolling `Body`
+and a fixed `Footer`. The default `layout="plain"` preserves the original padded
+content layout. Keep the sections as direct children of Content.
+
+```tsx
+<Overlay.Root>
+  <Overlay.Trigger asChild><Button>Edit note</Button></Overlay.Trigger>
+  <Overlay.Portal>
+    <Overlay.Backdrop />
+    <Overlay.Content layout="sections">
+      <Overlay.Header closeLabel="Close">
+        <Overlay.Title>Edit note</Overlay.Title>
+        <Overlay.Description>Update the note title.</Overlay.Description>
+      </Overlay.Header>
+      <Overlay.Body>{/* Fields or other dialog content */}</Overlay.Body>
+      <Overlay.Footer>
+        <Overlay.Close asChild><Button variant="outline">Cancel</Button></Overlay.Close>
+      </Overlay.Footer>
+    </Overlay.Content>
+  </Overlay.Portal>
+</Overlay.Root>
+```
+
+Header includes a pencil close button by default (`showClose={false}` hides it).
+Localize its accessible name and tooltip with `closeLabel`; `action` adds extra
+header controls. Header/Footer use pencil separators by default; disable each
+with `divided={false}`. Footer `align` is `start | center | end` (default end) and
+wraps actions when needed. `Overlay.CloseButton label="Close"` is also available
+for custom layouts. Native attributes, handlers and refs are forwarded.
+
+Keep a form inside Body and link Footer submit buttons with matching `form`/`id`
+attributes. This preserves validation and submission without wrapping the
+sections in another scroll container. Radix continues to manage Escape,
+outside interaction, modal focus trapping and focus return.
+
+## Navigation And Feedback
+
+`Tabs` exposes `Root`, `List`, `Trigger` and `Content`. It supports controlled or default values, horizontal/vertical orientation, RTL, automatic/manual activation and disabled triggers. `Content forceMount` preserves child state while hiding inactive panels. The selected pigment draws in and erases out, with reduced-motion fallbacks.
+
+`Root.size` accepts `sm | md | lg` (default `md`), and `Root.animated={false}` disables pigment animation. `List.align` accepts `start | center | end`, `List.fullWidth` distributes triggers equally, and `List.loop={false}` stops keyboard wrapping. `Trigger.startIcon` and `Trigger.endIcon` accept decorative React nodes; provide an accessible name for icon-only triggers. Small tabs keep a minimum 44px hit target.
+
+`List.divided` adds pencil separators between adjacent triggers (default false), following horizontal or vertical orientation without changing keyboard navigation.
+
+`Tooltip` exposes `Provider`, `Root`, `Trigger`, `Portal` and `Content`. Use it for supplementary non-interactive text, never as the only accessible name or essential instructions. Portal content inherits the trigger's theme.
+
+`Accordion` exposes `Root`, `Item`, `Header`, `Trigger` and `Content`. Use `type="single"` with a string value or `type="multiple"` with a string array. Single mode accepts `collapsible`; both support disabled items and keyboard navigation.
+
+```tsx
+<Tabs.Root defaultValue="notes">
+  <Tabs.List aria-label="Workspace">
+    <Tabs.Trigger value="notes">Notes</Tabs.Trigger>
+    <Tabs.Trigger value="drafts">Drafts</Tabs.Trigger>
+  </Tabs.List>
+  <Tabs.Content value="notes">Saved notes</Tabs.Content>
+  <Tabs.Content value="drafts">Unpublished drafts</Tabs.Content>
+</Tabs.Root>
+
+<Badge variant="success">Saved</Badge>
+<Separator decorative />
+<Skeleton style={{ width: 200, height: 20 }} />
+<Progress label="Uploading" value={60} />
+<Progress aria-label="Loading" value={null} />
+```
+
+`Badge` variants are `neutral`, `accent`, `success`, `warning`, `danger` and `info`. `Separator` has horizontal/vertical orientation and a decorative opt-out. `Skeleton` is a static, aria-hidden placeholder; mark its loading container `aria-busy`. `Progress` clamps numeric values to `0..max` (default 100); `null` is indeterminate without a fabricated percentage. Always provide a progress label.
+
+`Badge.size` accepts `sm | md | lg` with optional `startIcon` and `endIcon`. `Separator.weight` clamps to 0.3–2 (default 0.9). `Skeleton.radius` uses the existing 0–8px pencil corner contract. `Progress.size` selects a 12/16/24px track (`sm/md/lg`); `dir`, `aria-valuetext`, refs and native DOM attributes remain available. Tooltip exposes the underlying delay, alignment, collision and hoverable-content controls alongside `Content.surfaceRadius`.
+
+## Menus And Content
+
+`DropdownMenu` exposes `Root`, `Trigger`, `Portal`, `Content`, `Item`, `CheckboxItem`, `RadioGroup`, `RadioItem`, `Group`, `Label` and `Separator`. It supports controlled open state, placement/collision props, disabled items, keyboard navigation and focus return. Use `Trigger asChild` with a Button; use `Item.destructive` for dangerous actions. Portal content inherits the trigger theme. Submenus are not included yet.
+
+`Alert.Root` accepts `variant="info | success | warning | danger"`, an optional decorative `icon`, and native attributes. Compose with `Alert.Title` and `Alert.Description`. The default `role="status"` is polite; explicitly use `role="alert"` only for urgent feedback.
+
+`Avatar.Root` provides fixed `sm/md/lg` sizes (32/44/64px), with `Avatar.Image` and `Avatar.Fallback`. Images require `alt`; name meaningful fallback content with `role="img"` and `aria-label`. Fallback supports `delayMs` and appears when the image cannot load.
+
+`Card` exposes `Root`, `Header`, `Title`, `Description`, `Content` and `Footer`. Root accepts `variant="paper | quiet | outline"`, `radius` (0-8px) and `seed`; Title accepts `as="h2 | h3 | h4 | h5 | h6"` (default h3). Native props and refs remain available.
+
+`Table` exposes `Container`, `Root`, `Header`, `Body`, `Footer`, `Row`, `Head`, `Cell` and `Caption`, preserving native table semantics. Root accepts `density="compact | comfortable"`; `Row.selected` is visual emphasis only. Give the scrollable Container an accessible name and use a Caption and appropriate Head scope. Sorting, filtering, pagination and grid selection are not built in.
+
+Content layout options preserve existing defaults:
+
+- `Card.Root.size` and `Alert.Root.size` accept `sm | md | lg` for 12/16/24px padding (default md), without reducing text size.
+- `Card.Root.divided` defaults to true; `Header.divided` and `Footer.divided` override it locally. `Header.action` accepts an independent action node. `Content.padding="none"` removes content padding for edge-to-edge content. `Footer.justify` accepts `start | center | end | between`, respecting text direction.
+- `Alert.Root.appearance` accepts `soft | outline` (default soft). `actions` places actual controls after the message; it does not add automatic dismissal or focus changes.
+- `Avatar.Root.radius` clamps to 0-8px, including pencil and image corners; `bordered={false}` removes the outline. `Avatar.Image.fit` accepts `cover | contain` (default cover).
+- `Table.Root.striped`, `hoverable` and `stickyHeader` default to false. Constrain `Table.Container` with `style={{ maxHeight: 240 }}` for sticky scrolling. `captionSide` accepts `top | bottom`. `Head.align` and `Cell.align` accept logical `start | center | end`, retaining native alignment values for compatibility. Hover feedback does not imply row actions.
+
+## Travel Components
+
+`Calendar` wraps React DayPicker with default `appearance="itinerary"` day cards and optional `appearance="picker"`. It retains single/multiple/range selection, month control, disabled matchers, locale and keyboard navigation. Supply `selected` and `onSelect` for controlled selection. Events have independent `onEventSelect` handling; `displayRange` and `renderDayAccessory` customize the itinerary. Narrow itinerary grids retain seven columns and hide event text while preserving accessible names; picker targets remain at least 44px.
+
+`DayAgenda` takes a local `date` (`YYYY-MM-DD`) and `AgendaEvent[]` with `id`, `title`, optional `description`, `startMinute` and `endMinute`. Minutes are relative to that day's midnight. Cross-day intervals show continuation; missing times remain pending and missing ends remain points. Its vertical timeline uses a piecewise scale for readable short events and separate lanes for overlaps. `selectedEvent`, `onEventSelect`, `onPreviousDay` and `onNextDay` provide interaction. Supply localized labels, `locale` and optional `timeZoneLabel`; no time zones or flight durations are inferred.
+
+`JourneyMap` accepts `places`, optional GeoJSON `geography`, `routes`, `selectedPlace`, `onPlaceSelect` and required `attribution`. Place/route coordinates use latitude then longitude; GeoJSON retains longitude then latitude. Leaflet is loaded only in the browser. The map supports pan, zoom and reset, with an equivalent place-button list. It does not request location permissions, fetch map tiles, calculate routes or infer travel times. Demo geography is illustrative, not navigation data. Use `labels` to localize controls and failure feedback, and import `@inkra/react/styles.css` for all required map styles.
+
+## Pencil Primitives
+
+`PencilSurface` renders pencil material behind semantic DOM content. Available variants are `paper`, `action`, `quiet`, `badge`, `outline`, `danger`, `ghost`, `selection`, `wash`, and `full`. Use `selection` for the transparent selected-tab wash; it intentionally has no paper fill, outline, or bleed.
+
+`PencilText` keeps its string in the DOM for selection, copy, search, and assistive technology. Browser enhancement paints the same glyph geometry with the traced C lettering preset; unavailable canvas or font loading leaves the readable DOM fallback visible.
+
+`PencilIcon` accepts familiar SVG path data and deposits pigment along sampled geometry. See `docs/pencil-contract.md` in the workspace for the current alpha contract.
+
+`PencilLine` is an aria-hidden canvas decoration using the same pressure, grain, breaks, and repeated-pass renderer as surfaces and icons. It defaults to horizontal and supports a native vertical stroke without rotating a horizontal bitmap:
+
+```tsx
+<PencilLine seed="notes-divider" className="notes-divider" />
+<PencilLine orientation="vertical" seed="sidebar-divider" className="sidebar-divider" />
+```
+
+## Font license
+
+The package includes `Trip Map Hand`, a modified web subset of Yozai Light v0.868, under the SIL Open Font License 1.1. The font is not covered by Inkra's MIT software license. See `THIRD_PARTY_NOTICES.md` and `Yozai-OFL.txt` in the package.
+
+## Development
+
+```sh
+npm run typecheck
+npm test
+npm run pack:check
+```
+
+`npm test` builds the package before running the SSR and determinism tests. `pack:check` prints the files that would be included without publishing anything.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,39 @@
+# Third-Party Notices
+
+## Trip Map Hand font subset
+
+`dist/assets/ui-hand-yozai.woff2` is a web subset of Yozai Light v0.868 by LXGW, derived from work by Y.Oz. The subset uses the modified family name `Trip Map Hand` and is included to provide the handwriting geometry used by Inkra's pencil-text renderer.
+
+The font software is licensed under the SIL Open Font License 1.1. The complete license and copyright notice are included in `Yozai-OFL.txt`. The font is not covered by Inkra's MIT software license.
+
+Source: Yozai Font release v0.868.
+
+## Leaflet
+
+The distributed stylesheet includes Leaflet CSS and supporting image assets.
+
+BSD 2-Clause License
+
+Copyright (c) 2010-2023, Volodymyr Agafonkin
+Copyright (c) 2010-2011, CloudMade
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/Yozai-OFL.txt

@@ -0,0 +1,94 @@
+Copyright 2020, 2024 LXGW (https://github.com/lxgw/yozai-font)
+Copyright (c) 2021-03-07, Y.Oz (Y.OzVox) (http://yozvox.web.fc2.com), words containing "Y.Oz" or "YOz" are reserved as font names.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/Button.d.ts

@@ -0,0 +1,36 @@
+import type { AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes, ReactNode } from 'react';
+export type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive' | 'link';
+export type ButtonSize = 'xs' | 'sm' | 'md' | 'lg' | 'icon-xs' | 'icon-sm' | 'icon' | 'icon-lg';
+export type ButtonGroupOrientation = 'horizontal' | 'vertical';
+export type ButtonAlign = 'start' | 'center' | 'end';
+export type ButtonLoadingPosition = 'start' | 'center' | 'end';
+interface SharedButtonProps {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    loading?: boolean;
+    seed?: string | number;
+    startIcon?: ReactNode;
+    endIcon?: ReactNode;
+    fullWidth?: boolean;
+    align?: ButtonAlign;
+    loadingPosition?: ButtonLoadingPosition;
+    loadingIndicator?: ReactNode;
+}
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>, SharedButtonProps {
+}
+export interface ButtonLinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'children'>, SharedButtonProps {
+    children?: ReactNode;
+    disabled?: boolean;
+}
+export interface ButtonGroupProps extends HTMLAttributes<HTMLDivElement> {
+    orientation?: ButtonGroupOrientation;
+    size?: ButtonSize;
+    variant?: ButtonVariant;
+    disabled?: boolean;
+    fullWidth?: boolean;
+    equalWidth?: boolean;
+}
+export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
+export declare const ButtonLink: import("react").ForwardRefExoticComponent<ButtonLinkProps & import("react").RefAttributes<HTMLAnchorElement>>;
+export declare const ButtonGroup: import("react").ForwardRefExoticComponent<ButtonGroupProps & import("react").RefAttributes<HTMLDivElement>>;
+export {};

package/dist/Button.js

@@ -0,0 +1,89 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { createContext, forwardRef, useContext, useId } from 'react';
+import { PencilSurface } from './PencilSurface.js';
+import { PencilText } from './PencilText.js';
+import { PencilLine } from './PencilLine.js';
+import { InputActionContext } from './internal/InputActionContext.js';
+const ButtonGroupContext = createContext(null);
+function surfaceVariant(variant) {
+    if (variant === 'primary')
+        return 'action';
+    if (variant === 'secondary' || variant === 'ghost')
+        return 'quiet';
+    if (variant === 'outline')
+        return 'outline';
+    if (variant === 'destructive')
+        return 'danger';
+    return 'ghost';
+}
+function classNames(className) {
+    return ['inkra-button', className].filter(Boolean).join(' ');
+}
+function accessibleLabel(ariaLabel, loading, children) {
+    return ariaLabel ?? (loading && typeof children === 'string' ? children : undefined);
+}
+function ButtonVisual({ children, endIcon, loading, loadingPosition, loadingIndicator, seed, startIcon, variant }) {
+    const group = useContext(ButtonGroupContext);
+    const inputAction = useContext(InputActionContext);
+    const sharedOutline = group !== null || inputAction;
+    const indicator = _jsx("span", { "aria-hidden": "true", className: "inkra-button__loading-indicator", children: loadingIndicator ?? _jsx("span", { className: "inkra-button__spinner" }) });
+    const iconSlot = (side, icon) => {
+        const reserved = loadingPosition === side;
+        if (icon == null && !reserved)
+            return null;
+        return _jsxs("span", { "aria-hidden": "true", className: `inkra-button__icon inkra-button__icon--${side}`, "data-loading-slot": reserved || undefined, children: [_jsx("span", { className: "inkra-button__icon-content", children: icon }), reserved && loading ? indicator : null] });
+    };
+    const label = typeof children === 'string'
+        ? _jsx(PencilText, { seed: `${seed}-label`, children: children })
+        : children == null ? null : _jsx("span", { children: children });
+    return (_jsxs(_Fragment, { children: [_jsx(PencilSurface, { as: "span", className: "inkra-button__surface", clipContent: sharedOutline, radius: sharedOutline ? 0 : undefined, seed: seed, variant: inputAction ? 'ghost' : surfaceVariant(variant), children: _jsxs("span", { className: "inkra-button__content", children: [loading && loadingPosition === 'center' ? indicator : null, iconSlot('start', startIcon), label == null ? null : _jsxs("span", { className: "inkra-button__label", children: [label, variant === 'link' ? _jsx(PencilLine, { className: "inkra-button__underline", seed: `${seed}-underline`, weight: 0.9 }) : null] }), iconSlot('end', endIcon)] }) }), _jsx(PencilSurface, { as: "span", "aria-hidden": "true", className: "inkra-button__focus-ring", variant: "outline", seed: `${seed}-focus` }), group === null ? null : _jsx(PencilLine, { className: "inkra-button-group__divider", orientation: group.orientation === 'horizontal' ? 'vertical' : 'horizontal', seed: `${seed}-group-divider` })] }));
+}
+export const Button = forwardRef(function Button({ children, 'aria-label': ariaLabel, className, disabled = false, endIcon, loading = false, loadingPosition = 'center', loadingIndicator, fullWidth = false, align = 'center', seed, size: sizeProp, startIcon, type = 'button', variant: variantProp, ...props }, ref) {
+    const id = useId();
+    const group = useContext(ButtonGroupContext);
+    const size = sizeProp ?? group?.size ?? 'md';
+    const variant = variantProp ?? group?.variant ?? 'primary';
+    const position = size.startsWith('icon') ? 'center' : loadingPosition;
+    const resolvedSeed = seed ?? `inkra-button-${id}`;
+    return (_jsx("button", { ...props, "aria-label": accessibleLabel(ariaLabel, loading, children), "aria-busy": loading || undefined, className: classNames(className), "data-loading": loading || undefined, "data-loading-position": position, "data-full-width": fullWidth && !size.startsWith('icon') || undefined, "data-align": align, "data-size": size, "data-variant": variant, disabled: disabled || loading || group?.disabled, ref: ref, type: type, children: _jsx(ButtonVisual, { endIcon: endIcon, loading: loading, loadingPosition: position, loadingIndicator: loadingIndicator, seed: resolvedSeed, startIcon: startIcon, variant: variant, children: children }) }));
+});
+export const ButtonLink = forwardRef(function ButtonLink({ children, 'aria-label': ariaLabel, className, disabled = false, endIcon, href, loading = false, loadingPosition = 'center', loadingIndicator, fullWidth = false, align = 'center', onAuxClick, onClick, onKeyDown, seed, size: sizeProp, startIcon, tabIndex, variant: variantProp, ...props }, ref) {
+    const id = useId();
+    const group = useContext(ButtonGroupContext);
+    const size = sizeProp ?? group?.size ?? 'md';
+    const variant = variantProp ?? group?.variant ?? 'primary';
+    const position = size.startsWith('icon') ? 'center' : loadingPosition;
+    const resolvedSeed = seed ?? `inkra-button-link-${id}`;
+    const interactionDisabled = disabled || loading || group?.disabled;
+    const handleClick = (event) => {
+        if (interactionDisabled) {
+            event.preventDefault();
+            event.stopPropagation();
+            return;
+        }
+        onClick?.(event);
+    };
+    const handleAuxClick = (event) => {
+        if (interactionDisabled) {
+            event.preventDefault();
+            event.stopPropagation();
+            return;
+        }
+        onAuxClick?.(event);
+    };
+    const handleKeyDown = (event) => {
+        if (interactionDisabled) {
+            if (event.key === 'Enter' || event.key === ' ')
+                event.preventDefault();
+            event.stopPropagation();
+            return;
+        }
+        onKeyDown?.(event);
+    };
+    return (_jsx("a", { ...props, "aria-label": accessibleLabel(ariaLabel, loading, children), "aria-busy": loading || undefined, "aria-disabled": interactionDisabled || undefined, className: classNames(className), "data-disabled": interactionDisabled || undefined, "data-loading": loading || undefined, "data-loading-position": position, "data-full-width": fullWidth && !size.startsWith('icon') || undefined, "data-align": align, "data-size": size, "data-variant": variant, href: interactionDisabled ? undefined : href, onAuxClick: handleAuxClick, onClick: handleClick, onKeyDown: handleKeyDown, ref: ref, tabIndex: interactionDisabled ? -1 : tabIndex, children: _jsx(ButtonVisual, { endIcon: endIcon, loading: loading, loadingPosition: position, loadingIndicator: loadingIndicator, seed: resolvedSeed, startIcon: startIcon, variant: variant, children: children }) }));
+});
+export const ButtonGroup = forwardRef(function ButtonGroup({ children, className, orientation = 'horizontal', size, variant, disabled = false, fullWidth = false, equalWidth = false, ...props }, ref) {
+    const classes = ['inkra-button-group', className].filter(Boolean).join(' ');
+    const id = useId();
+    return (_jsx(ButtonGroupContext.Provider, { value: { orientation, size, variant, disabled }, children: _jsx(PencilSurface, { ...props, className: classes, "data-orientation": orientation, "data-full-width": fullWidth || undefined, "data-equal-width": equalWidth || undefined, "aria-disabled": disabled || undefined, radius: 8, ref: ref, role: "group", seed: `inkra-button-group-${id}`, variant: "outline", children: children }) }));
+});

package/dist/PencilIcon.d.ts

@@ -0,0 +1,22 @@
+import type { CanvasHTMLAttributes } from 'react';
+export interface PencilIconPath {
+    d: string;
+    mode?: 'stroke' | 'wash' | 'scuff';
+}
+export interface PencilIconBadge {
+    paths: readonly PencilIconPath[];
+    sourceSize?: number;
+    position?: 'top-start' | 'top-end' | 'bottom-start' | 'bottom-end';
+    /** Relative canvas size, clamped to 0.35-0.65. Defaults to 0.55. */
+    scale?: number;
+}
+export interface PencilIconProps extends Omit<CanvasHTMLAttributes<HTMLCanvasElement>, 'children' | 'height' | 'width'> {
+    paths: readonly PencilIconPath[];
+    badge?: PencilIconBadge;
+    seed?: string | number;
+    size?: number;
+    sourceSize?: number;
+    active?: boolean;
+    decorative?: boolean;
+}
+export declare const PencilIcon: import("react").ForwardRefExoticComponent<PencilIconProps & import("react").RefAttributes<HTMLCanvasElement>>;