@dextinity/ui 0.0.0-stage → 11.0.0-canary-20261029073435

package/LICENSE

@@ -0,0 +1,24 @@
+BSD 2-Clause License
+
+Copyright (c) 2023, Vivid Planet Software GmbH
+
+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/README.md

@@ -1,3 +1,191 @@
-# Temporary Holding Version
+# @dextinity/ui
 
-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.
+An **experimental**, UI-only React component library. It contains no routing, forms, data fetching, or other non-UI logic, and it is not specific to the admin: any React application can use it.
+
+It builds on an unstyled foundation rather than evolving the MUI-based components of `@dextinity/admin`; `@base-ui/react` is the chosen foundation.
+
+## Usage
+
+Import the styles once, in the application's entry file:
+
+```ts
+import "@dextinity/ui/css";
+```
+
+## Experimental
+
+Any export may change or be removed at any time, without deprecation notice. Changesets are not created for changes within this package.
+
+## Non-goals
+
+- **No non-UI logic.** Forms (`final-form`, `react-hook-form`), routing (`react-router`), data fetching (Apollo), and similar concerns stay out.
+- **No dependency on `@mui/material`, `@mui/system`, Emotion, or any other part of the existing `@dextinity/admin` styling stack.** This package is a fresh foundation; cross-imports reintroduce the competing system it removes.
+
+## Folder and file names
+
+- **Feature folders** use camelCase (`button/`, `textField/`).
+- **Component file**: `<ComponentName>.tsx` (PascalCase), one per component feature.
+- **Non-component code file**: `<featureName>.ts(x)` (camelCase) for utilities and hooks.
+- **Styles**: `<ComponentName>.module.scss` (CSS Modules with SCSS).
+
+## Component conventions
+
+### Exports
+
+- Props are exported as an interface named `<ComponentName>Props`, never a type alias.
+- The resolved configuration is exported as a type named `<ComponentName>OwnerState`.
+- The component is exported as `<ComponentName>`.
+
+### TSDoc
+
+Components and utilities are documented in TSDoc on the export itself, so the docs ship with the package, get picked up by Storybook, and stay next to the code.
+
+Keep each comment as close as possible to what it describes: the component comment says what the component is for, while a prop's description and its `@defaultValue` go on the prop. Say what a feature does, not how (leave out the rendered element, prop forwarding, the base-ui foundation) and not why (the commit carries that); don't merely restate the name. Keep it as short as the feature allows. The shared override-API members — `className`, `slots`, `slotProps`, and the `OwnerState` type — share the wording shown below, extended only where a component needs more detail.
+
+```tsx
+/**
+ * Buttons allow users to take actions, and make choices, with a single tap.
+ */
+export function Button(props: ButtonProps) {
+    // ...
+}
+
+/**
+ * The resolved configuration that influences the component's appearance or behavior.
+ */
+export type ButtonOwnerState = {
+    variant: "primary" | "secondary";
+    disabled: boolean;
+};
+
+export interface ButtonProps {
+    /**
+     * Use `primary` only for the single main action on a page, dialog, etc.
+     *
+     * @defaultValue `"primary"`
+     */
+    variant?: "primary" | "secondary";
+    /** Added alongside the component's own classes. */
+    className?: string;
+    /** Sets which element a named inner part renders as. */
+    slots?: ButtonSlots;
+    /** Props for each slot, merged with the slot's own props rather than replacing them. */
+    slotProps?: ButtonSlotProps;
+}
+```
+
+A change that makes a comment inaccurate updates it in the same change.
+
+### Root element props
+
+A component extends the props of its root element and passes the ones it doesn't handle itself to that element, so a consumer can set any attribute or event handler the root element accepts without us maintaining a dedicated prop for each. By default it doesn't re-declare or document them; they stay as the root element defines them. It may still re-declare one to support it as a documented feature.
+
+### Override props
+
+The exported components share one set of override props; each offers the ones that apply to it. The [styling contract](#styling-contract) is the primary way to style a component; these props do what it can't — place and swap inner parts, and set or vary their props.
+
+- **`className`** — a string, merged with the contract classes, never replacing them. It is not a function: every value in `ownerState` already emits a `data-*` attribute, so an `ownerState`-dependent class would add nothing.
+- **`slots`** — sets which element a named inner part renders as. The root is not a slot — it is the component's own outermost element, configured through the component's top-level props directly (`className`, event handlers, ARIA, …).
+- **`slotProps`** — props for those same inner parts, as an object **or** a function of `ownerState`. Their type follows the element chosen for the slot in `slots`, and falls back to the slot's default element when `slots` is omitted. They are merged with the component's own props, so a contract class or handler is never dropped.
+- **`ownerState`** — one object per component: the resolved configuration (`variant`, `disabled`, …) that influences the component's appearance or behavior; the root's `data-*` attributes are derived from it. It holds no transient interaction state (hover/press/focus).
+
+A slot accepts any element only while the component injects nothing element-specific into it — a universal prop like `className` is fine, `href` is not. When the component injects an element-specific prop, the slot narrows to the elements that accept it — a minimum prop contract any intrinsic element or custom component can satisfy. A part limited for semantic reasons instead — a heading restricted to `h1`–`h6` — takes a fixed set of allowed elements.
+
+### Styling contract
+
+Every component emits a stable, predictable contract for consumer styling: a consumer writes plain CSS against it, with no React API involvement required. It is part of the public API — renaming an emitted class or `data-*` attribute is a breaking change.
+
+The contract has two parts: **structural class names** for a component's elements, and **owner-state styling** for the resolved configuration, expressed as `data-*` attributes.
+
+**Structural class names** identify a component's root and its parts:
+
+- **Root** — `dextinity<Component>`. The outermost element of a component, camelCased. Examples: `dextinityButton`, `dextinityTextField`.
+- **Parts** — `dextinity<Component>__<partName>`. A part is a named sub-element; the part name is camelCased. Examples: `dextinityButton__startIcon`, `dextinityTextField__label`.
+
+**Owner-state styling** uses `data-*` attributes on the root element, following base-ui's own conversion of an owner-state object:
+
+- **Enum state** → a single valued attribute: `data-variant="primary"`.
+- **Boolean state** → presence only: `data-disabled` (absent when false).
+- The attribute name is `data-` + the lowercased owner-state key. Owner-state keys are single lowercase words, so the name needs no kebab-casing.
+
+**Emission.** These attributes cover owner-state values only; parts are class names. How a component emits them depends on its foundation: one rendered through `useRender` passes `state: ownerState` for base-ui to convert; one built on a base-ui primitive lets the primitive emit the state it owns and passes the rest inline (`data-variant={variant}`).
+
+**Composition.** When a component of this package is used as the root of another component, both root classes appear on the same element — a `CustomButton` rendering through `Button` produces `dextinityButton dextinityCustomButton`. Either layer is targetable.
+
+**Authoring source.** The SCSS module's local class names match the public part names; the stylesheet's file name is the single source of a component's emitted name. The mapping:
+
+| Source local | Emitted DOM class            |
+| ------------ | ---------------------------- |
+| `root`       | `dextinityButton`            |
+| `startIcon`  | `dextinityButton__startIcon` |
+
+- A component with no single dominant element names no class `root`.
+- Owner-state styles use attribute selectors nested under `.root` with `&` (`.root { &[data-variant="primary"] { … } }`).
+
+### Stories
+
+Stories live under the "Components" section. Each consumer-facing component has its own story file in an `__stories__/` directory next to its source; story-only helpers such as decorators live in [`src/storybook/`](src/storybook). The component's TSDoc and prop table (see [TSDoc](#tsdoc)) drive its autodocs page, so stories don't restate it.
+
+#### Main story
+
+`__stories__/<ComponentName>.stories.tsx`, included in autodocs, is the component's consumer-facing documentation: a new variant, feature, or state gets a story in the same change, keeping the docs page current.
+
+Stories use [Component Story Format 3](https://storybook.js.org/docs/api/csf), typed with `satisfies` so `meta` is checked against the component's props and each story inherits its args:
+
+```tsx
+const meta = {
+    component: Button,
+    args: { children: "Button", onClick: fn() },
+} satisfies Meta<typeof Button>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+```
+
+`meta.args` holds only what a practical example needs: required content such as `children`, and the event handlers that make it interactive. It omits any prop that has a component default — a defaulted prop is set in the story that demonstrates it instead.
+
+The first story is `Default`, the autodocs example: it sets no args of its own, showing that smallest practical example. Each prop that changes the component visibly then gets one story per option; a prop that changes only semantics, such as `Typography`'s `element`, stays a control, since a story per value would look the same.
+
+Each declared prop is exposed as a control through `argTypes`, by kind:
+
+- **Boolean** — a toggle.
+- **Enum** — `radio` for three options or fewer, `select` for more.
+- **`ReactNode`** — a `select` whose `options` are labels and whose `mapping` resolves each to the node. The built-in empty choice covers the unset case.
+- **Override-API props** (`className`, `slots`, `slotProps`, `ref`, `render`) — `control: false`, keeping the prop-table row without an unusable control.
+- **Event handlers** — `fn()` from `storybook/test`, so calls show in the Actions panel and an interaction test can verify the handler ran.
+
+#### Dev story
+
+`__stories__/<name>.dev.stories.tsx`, optional, nests its title under a `Dev` segment (`Components/<Component>/Dev/<Name>`) and sets `tags: ["!autodocs"]` in its meta, keeping these out of the consumer docs. A dev story serves any development, testing, or debugging need, so add them freely — e.g. reproduce a bug in a dev story and use it to confirm the fix, rather than reaching for the Dextinity demo or a consuming project.
+
+## Testing
+
+Test the behavior and contracts a consumer depends on, not the implementation. Each test protects one such behavior; anything written only for coverage, or that just restates the type checker or the implementation, is left out.
+
+What to test, and with which kind of test:
+
+- **Utility logic** — a unit test (`unit` project, `jsdom`) next to the utility, exercising it directly in isolation.
+- **A component's render contract** — the class names and `data-*` attributes consumers style and target — a unit test next to the component. Assert the contract, not the styles it produces.
+- **A type-only contract** — typing with no runtime behavior, such as slot-prop inference — a compile-time test (`@ts-expect-error` on what must not compile), caught by `tsc`.
+- **Component behavior** — click, keyboard, focus, disabled — a Storybook interaction test (a story's `play` function), run in a real browser.
+
+Not worth a test:
+
+- **That a component renders** — every story already runs as a browser test, so a rendering story is the coverage.
+- **Appearance** — colors, sizes, spacing — reviewed visually in the stories, never asserted.
+- **Dev-local tooling** — story-only helpers — a failure is loud and local. Exception: code whose regression is silent or reaches consumers, such as the class-name mapping in `src/cssModules/`.
+
+Run from `packages/ui`: `pnpm run test:unit`, `pnpm run test:storybook`, and `pnpm run test:watch`.
+
+## Theme
+
+Components read their colors and metrics from CSS custom properties (`var(--dextinity-button-…)`, `var(--dextinity-color-…)`, `var(--dextinity-typography-…)`) with **no fallback** — an unthemed component renders visibly unstyled rather than silently drifting to a default. There is no runtime JS theme object.
+
+### Token layers
+
+The tokens are defined in five SCSS partials under [`src/theme/`](src/theme), composed into the provider module with `@use` and wrapped in a single `@layer dextinity`: `_primitives.scss` (raw values, internal), `_brand.scss`, `_responsive.scss`, `_semantic.scss`, and `_components.scss`. The prop-value types live in [`src/theme/types.ts`](src/theme/types.ts).
+
+### Selecting a color scheme
+
+`Theme` selects the active color scheme. It stays a pure function of its props — reading no `window`, `localStorage`, or `matchMedia` — so it renders the same on server and client; switching, OS-scheme resolution, and preventing the first-paint flash on SSR stay in consumer code.

package/lib/components/button/Button.d.ts

@@ -0,0 +1,60 @@
+import { Button as BaseButton } from "@base-ui/react/button";
+import type { ElementType, ReactNode } from "react";
+import { type SlotPropsValue } from "../../utils/slotProps";
+type ButtonVariant = "primary" | "secondary";
+/**
+ * The resolved configuration that influences the component's appearance or behavior.
+ */
+export type ButtonOwnerState = {
+    variant: ButtonVariant;
+    disabled: boolean;
+};
+interface ButtonSlots<StartIcon extends ElementType, EndIcon extends ElementType> {
+    /**
+     * Element for the `startIcon` slot.
+     *
+     * @defaultValue `span`
+     */
+    startIcon?: StartIcon;
+    /**
+     * Element for the `endIcon` slot.
+     *
+     * @defaultValue `span`
+     */
+    endIcon?: EndIcon;
+}
+interface ButtonSlotProps<StartIcon extends ElementType, EndIcon extends ElementType> {
+    /** Props for the `startIcon` slot. */
+    startIcon?: SlotPropsValue<ButtonOwnerState, StartIcon>;
+    /** Props for the `endIcon` slot. */
+    endIcon?: SlotPropsValue<ButtonOwnerState, EndIcon>;
+}
+export interface ButtonProps<StartIcon extends ElementType = "span", EndIcon extends ElementType = "span"> extends Omit<BaseButton.Props, "className"> {
+    /**
+     * Visual style.
+     *
+     * @defaultValue `"primary"`
+     */
+    variant?: ButtonVariant;
+    /**
+     * Prevents interaction with the button.
+     *
+     * @defaultValue `false`
+     */
+    disabled?: boolean;
+    /** Added alongside the component's own classes. */
+    className?: string;
+    /** Sets which element a named inner part renders as. */
+    slots?: ButtonSlots<StartIcon, EndIcon>;
+    /** Props for each slot, merged with the slot's own props rather than replacing them. */
+    slotProps?: ButtonSlotProps<StartIcon, EndIcon>;
+    /** The icon to render before the button's text. */
+    startIcon?: ReactNode;
+    /** The icon to render after the button's text. */
+    endIcon?: ReactNode;
+}
+/**
+ * A button for triggering actions.
+ */
+export declare function Button<StartIcon extends ElementType = "span", EndIcon extends ElementType = "span">({ disabled, type, variant, className, slots, slotProps, startIcon, endIcon, children, ...restProps }: ButtonProps<StartIcon, EndIcon>): import("react").JSX.Element;
+export {};

package/lib/components/button/Button.js

@@ -0,0 +1,47 @@
+import { resolveSlotProps } from "../../utils/slotProps.js";
+import Button_module_default from "./Button.module.js";
+import { Button } from "@base-ui/react/button";
+import { clsx } from "clsx";
+import { jsx, jsxs } from "react/jsx-runtime";
+//#region src/components/button/Button.tsx
+/**
+* A button for triggering actions.
+*/
+function Button$1({ disabled = false, type = "button", variant = "primary", className, slots, slotProps, startIcon, endIcon, children, ...restProps }) {
+	const ownerState = {
+		variant,
+		disabled
+	};
+	const StartIconSlot = slots?.startIcon ?? "span";
+	const EndIconSlot = slots?.endIcon ?? "span";
+	const startIconProps = resolveSlotProps({
+		ownProps: { className: Button_module_default.startIcon },
+		slotProps: slotProps?.startIcon,
+		ownerState
+	});
+	const endIconProps = resolveSlotProps({
+		ownProps: { className: Button_module_default.endIcon },
+		slotProps: slotProps?.endIcon,
+		ownerState
+	});
+	return /* @__PURE__ */ jsxs(Button, {
+		...restProps,
+		type,
+		disabled: ownerState.disabled,
+		"data-variant": ownerState.variant,
+		className: clsx(Button_module_default.root, className),
+		children: [
+			startIcon != null && /* @__PURE__ */ jsx(StartIconSlot, {
+				...startIconProps,
+				children: startIcon
+			}),
+			children,
+			endIcon != null && /* @__PURE__ */ jsx(EndIconSlot, {
+				...endIconProps,
+				children: endIcon
+			})
+		]
+	});
+}
+//#endregion
+export { Button$1 as Button };

package/lib/components/button/Button.module.js

@@ -0,0 +1,11 @@
+//#region src/components/button/Button.module.scss
+var root = "dextinityButton";
+var startIcon = "dextinityButton__startIcon";
+var endIcon = "dextinityButton__endIcon";
+var Button_module_default = {
+	root,
+	startIcon,
+	endIcon
+};
+//#endregion
+export { Button_module_default as default, endIcon, root, startIcon };

package/lib/components/theme/Theme.d.ts

@@ -0,0 +1,16 @@
+import type { ComponentPropsWithoutRef } from "react";
+import type { ThemeColorScheme } from "../../theme/types";
+export interface ThemeProps extends ComponentPropsWithoutRef<"div"> {
+    /**
+     * The active color scheme.
+     *
+     * @defaultValue "light"
+     */
+    colorScheme?: ThemeColorScheme | (string & {});
+    /** Added alongside the component's own classes. */
+    className?: string;
+}
+/**
+ * Scopes the active color scheme to its subtree. Wrap an application, or a section of one.
+ */
+export declare function Theme({ colorScheme, className, children, ...restProps }: ThemeProps): import("react").JSX.Element;

package/lib/components/theme/Theme.js

@@ -0,0 +1,17 @@
+import Theme_module_default from "./Theme.module.js";
+import { clsx } from "clsx";
+import { jsx } from "react/jsx-runtime";
+//#region src/components/theme/Theme.tsx
+/**
+* Scopes the active color scheme to its subtree. Wrap an application, or a section of one.
+*/
+function Theme({ colorScheme = "light", className, children, ...restProps }) {
+	return /* @__PURE__ */ jsx("div", {
+		...restProps,
+		"data-dextinity-color-scheme": colorScheme,
+		className: clsx(Theme_module_default.root, className),
+		children
+	});
+}
+//#endregion
+export { Theme };

package/lib/components/theme/Theme.module.js

@@ -0,0 +1,5 @@
+//#region src/components/theme/Theme.module.scss
+var root = "dextinityTheme";
+var Theme_module_default = { root };
+//#endregion
+export { Theme_module_default as default, root };

package/lib/components/typography/Typography.d.ts

@@ -0,0 +1,43 @@
+import { useRender } from "@base-ui/react/use-render";
+import type { HTMLAttributes, Ref } from "react";
+type TypographyVariant = "headline" | "body";
+type TypographyElement = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "p" | "span";
+/**
+ * The resolved configuration that influences the component's appearance or behavior.
+ */
+export type TypographyOwnerState = {
+    variant: TypographyVariant;
+};
+export interface TypographyProps extends Omit<HTMLAttributes<HTMLElement>, "className"> {
+    /**
+     * Visual style. Each variant has a default semantic element.
+     *
+     * @defaultValue `"body"`
+     */
+    variant?: TypographyVariant;
+    /**
+     * The semantic element to render, overriding the variant's default.
+     *
+     * @defaultValue The variant's default element
+     */
+    element?: TypographyElement;
+    /** Added alongside the component's own classes. */
+    className?: string;
+    /** Ref forwarded to the root element. */
+    ref?: Ref<HTMLElement>;
+    /**
+     * Render a custom root element instead of the variant's default.
+     *
+     * @example
+     * ```tsx
+     * <Typography render={<label htmlFor="email" />}>Email</Typography>
+     * ```
+     */
+    render?: useRender.RenderProp<TypographyOwnerState>;
+}
+/**
+ * Renders a single block of text in one of several visual variants, each
+ * mapping to a default semantic element.
+ */
+export declare function Typography({ variant, element, className, children, ref, render, ...restProps }: TypographyProps): import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>>;
+export {};

package/lib/components/typography/Typography.js

@@ -0,0 +1,29 @@
+import Typography_module_default from "./Typography.module.js";
+import { clsx } from "clsx";
+import { useRender } from "@base-ui/react/use-render";
+//#region src/components/typography/Typography.tsx
+var variantElement = {
+	headline: "h2",
+	body: "p"
+};
+/**
+* Renders a single block of text in one of several visual variants, each
+* mapping to a default semantic element.
+*/
+function Typography({ variant = "body", element, className, children, ref, render, ...restProps }) {
+	const ownerState = { variant };
+	const tagName = element ?? variantElement[ownerState.variant];
+	return useRender({
+		render,
+		ref,
+		state: ownerState,
+		defaultTagName: tagName,
+		props: {
+			...restProps,
+			className: clsx(Typography_module_default.root, className),
+			children
+		}
+	});
+}
+//#endregion
+export { Typography };

package/lib/components/typography/Typography.module.js

@@ -0,0 +1,5 @@
+//#region src/components/typography/Typography.module.scss
+var root = "dextinityTypography";
+var Typography_module_default = { root };
+//#endregion
+export { Typography_module_default as default, root };

package/lib/icons/ArrowRightIcon.d.ts

@@ -0,0 +1,2 @@
+import type { SVGProps } from "react";
+export declare function ArrowRightIcon(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;

package/lib/icons/FavoriteIcon.d.ts

@@ -0,0 +1,2 @@
+import type { SVGProps } from "react";
+export declare function FavoriteIcon(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;

package/lib/index.d.ts

@@ -0,0 +1,3 @@
+export { Button, type ButtonOwnerState, type ButtonProps } from "./components/button/Button";
+export { Theme, type ThemeProps } from "./components/theme/Theme";
+export { Typography, type TypographyOwnerState, type TypographyProps } from "./components/typography/Typography";

package/lib/index.js

@@ -0,0 +1,4 @@
+import { Button } from "./components/button/Button.js";
+import { Theme } from "./components/theme/Theme.js";
+import { Typography } from "./components/typography/Typography.js";
+export { Button, Theme, Typography };