@simple-base/contracts 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Reda Salmi
+
+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

@@ -0,0 +1,121 @@
+# @simple-base/contracts
+
+Shared component option types and default constants for framework adapters such as
+Solid and React. CSS owns styling; adapters own rendering, native props, and
+behavior. This package has no runtime dependencies.
+
+`packages/css/styles/` is the source of truth for supported styling options. Only
+components with shared custom options need a contract. There are no class-name
+maps, attribute-name maps, CSS-property maps, or class-only contracts.
+
+## Usage
+
+```ts
+import {
+  buttonDefaults,
+  type ButtonOptions,
+  type ButtonSize,
+  type ButtonVariant,
+} from "@simple-base/contracts";
+```
+
+The same exports are available from `@simple-base/contracts/button`. Other
+subpaths are `/badge`, `/card`, `/combobox`, `/placement`, `/select`, and
+`/status`.
+
+Adapters compose the shared options with their framework's native element props,
+apply defaults when options are omitted, and emit the appropriate CSS classes and
+attributes directly. Share framework-neutral public configuration and value
+callbacks. Children, refs, framework-specific DOM events, native element prop
+interfaces, internal context, and accessibility implementation stay in the adapters.
+Every adapter part accepts a reactive `class` plus the native attributes for the
+element it renders, excluding the attributes the widget owns. Widget event
+handlers are composed with consumer handlers rather than replaced.
+
+```ts
+export type ButtonOptions = {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+};
+
+export const buttonDefaults = {
+  variant: "primary",
+  size: "medium",
+} as const satisfies Required<ButtonOptions>;
+```
+
+Types are erased from runtime JavaScript. Only the default constants are runtime
+exports; there are no allowed-value arrays without a runtime use case.
+
+## Available options
+
+| Component   | Types                                          | Defaults                              |
+| ----------- | ---------------------------------------------- | ------------------------------------- |
+| Button      | `ButtonVariant`, `ButtonSize`, `ButtonOptions` | `buttonDefaults`: `primary`, `medium` |
+| Badge       | `BadgeVariant`, `BadgeSize`, `BadgeOptions`    | `badgeDefaults`: `default`, `medium`  |
+| Card        | `CardVariant`, `CardOptions`                   | `cardDefaults`: `padding: false`      |
+| Combobox    | `ComboboxOption`, `ComboboxOptions`            | No defaults                           |
+| Select      | `SelectOption`, `SelectOptions`                | No defaults                           |
+| Status line | `StatusValue`, `StatusOptions`                 | No default status                     |
+| Alert       | `AlertStatus`, `AlertOptions`                  | No default status                     |
+| Toast       | `ToastStatus`, `ToastOptions`                  | `toastDefaults`: `status: "success"`  |
+
+- Button variants: `primary`, `secondary`, `tertiary`, `ghost`, `danger`,
+  `danger-subtle`. Sizes: `small`, `medium`, `large`. Apply the default attributes
+  explicitly; the bare CSS class is not identical to every default variant rule.
+- Badge variants: `default`, `success`, `danger`, `warning`, `info`, `accent`,
+  `command`, `outline`, `muted`. Sizes: `small`, `medium`.
+- Card variants: `flat`, `rule`. Omit `variant` for the base card; there is no
+  explicit `default` variant. `padding` is boolean and maps to
+  `data-padding="true"` when enabled.
+- `ComboboxOption` contains `label`, a unique `value`, and optional `disabled`.
+  `ComboboxOptions` defines the shared root API: required `id`, `label`, `options`,
+  and `onValueChange`, plus optional `placeholder`, `value`, `disabled`,
+  `invalid`, `required`, `name`, `placement`, and `onOpenChange`. The callback
+  receives the selected option's string value, or an empty string when selection
+  is cleared. Adapters add their own children type and keep context and rendering
+  internal.
+- `SelectOption` mirrors `ComboboxOption`, and `SelectOptions` mirrors
+  `ComboboxOptions` for the keyboard-driven single-select. The `placeholder`
+  string renders in place of the value text until an option is selected. Both
+  option lists stay independent so each adapter can evolve its own surface.
+- `value` is the controlled counterpart of `onValueChange`. An empty string means
+  no selection, and omitting `value` leaves the component uncontrolled. Adapters
+  must therefore treat `""` as a controlled empty selection, not as uncontrolled.
+- `disabled` dims and blocks the field, `invalid` switches the border and focus
+  ring to the danger tokens, and `required` adds the label marker. `placement` is
+  the shared `top`/`bottom` union with `-start` and `-end` variants and picks the
+  popup side; it is deliberately narrower than the adapter's positioning options,
+  not a pass-through. `onOpenChange` reports popup visibility for lazy loading
+  and analytics.
+- `name` has different meaning per component. Combobox applies it to the visible
+  input, so the submitted value is the option label, not its value. Select keeps a
+  hidden native select for the option value and always renders it, so the label
+  stays associated and form reset and fieldset state are tracked; `name` alone
+  decides whether the control is submitted.
+- Status line statuses: `success`, `danger`, `info`.
+- Alert statuses: `danger`, `info`. Only the border changes with status; the CSS
+  keeps the alert mark danger-colored.
+- Toast status: `success` only. Status line, alert, and toast types are exported
+  from `/status`, but intentionally do not share an interchangeable status union.
+
+Native-only components such as checkbox, input, and the plain `.sb-select`
+pattern do not need shared custom options. Typography classes and the progress
+CSS custom property remain part of the CSS API, not this package.
+
+## Migration from the class-map contracts
+
+Use `buttonDefaults`, `badgeDefaults`, `cardDefaults`, and `toastDefaults` instead
+of the corresponding `*Contract.defaults`. Use CSS class and attribute names
+directly in adapters. Class-only contracts and their subpaths have been removed.
+Existing option type names are unchanged.
+
+## Verification
+
+```sh
+pnpm --filter @simple-base/contracts typecheck
+pnpm --filter @simple-base/contracts build
+```
+
+These commands check the shared types and build the runtime defaults and type
+declarations.

package/dist/badge.d.ts

@@ -0,0 +1,12 @@
+//#region src/badge.d.ts
+export type BadgeVariant = "default" | "success" | "danger" | "warning" | "info" | "accent" | "command" | "outline" | "muted";
+export type BadgeSize = "small" | "medium";
+export type BadgeOptions = {
+  variant?: BadgeVariant;
+  size?: BadgeSize;
+};
+export declare const badgeDefaults: {
+  readonly variant: "default";
+  readonly size: "medium";
+};
+//#endregion

package/dist/badge.js

@@ -0,0 +1,7 @@
+//#region src/badge.ts
+const badgeDefaults = {
+	variant: "default",
+	size: "medium"
+};
+//#endregion
+export { badgeDefaults };

package/dist/button.d.ts

@@ -0,0 +1,12 @@
+//#region src/button.d.ts
+export type ButtonVariant = "primary" | "secondary" | "tertiary" | "ghost" | "danger" | "danger-subtle";
+export type ButtonSize = "small" | "medium" | "large";
+export type ButtonOptions = {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+};
+export declare const buttonDefaults: {
+  readonly variant: "primary";
+  readonly size: "medium";
+};
+//#endregion

package/dist/button.js

@@ -0,0 +1,7 @@
+//#region src/button.ts
+const buttonDefaults = {
+	variant: "primary",
+	size: "medium"
+};
+//#endregion
+export { buttonDefaults };

package/dist/card.d.ts

@@ -0,0 +1,11 @@
+//#region src/card.d.ts
+export type CardVariant = "flat" | "rule";
+export type CardOptions = {
+  variant?: CardVariant;
+  padding?: boolean;
+};
+export declare const cardDefaults: {
+  readonly variant: "flat";
+  readonly padding: false;
+};
+//#endregion

package/dist/card.js

@@ -0,0 +1,7 @@
+//#region src/card.ts
+const cardDefaults = {
+	variant: "flat",
+	padding: false
+};
+//#endregion
+export { cardDefaults };

package/dist/combobox.d.ts

@@ -0,0 +1,22 @@
+import { Placement } from "./placement.js";
+//#region src/combobox.d.ts
+export type ComboboxOption = {
+  label: string;
+  value: string;
+  disabled?: boolean;
+};
+export type ComboboxOptions = {
+  id: string;
+  label: string;
+  name?: string;
+  placeholder?: string;
+  options: ComboboxOption[];
+  value?: string;
+  disabled?: boolean;
+  invalid?: boolean;
+  required?: boolean;
+  placement?: Placement;
+  onValueChange: (value: string) => void;
+  onOpenChange?: (open: boolean) => void;
+};
+//#endregion

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { BadgeOptions, BadgeSize, BadgeVariant, badgeDefaults } from "./badge.js";
+import { ButtonOptions, ButtonSize, ButtonVariant, buttonDefaults } from "./button.js";
+import { CardOptions, CardVariant, cardDefaults } from "./card.js";
+import { Placement } from "./placement.js";
+import { ComboboxOption, ComboboxOptions } from "./combobox.js";
+import { SelectOption, SelectOptions } from "./select.js";
+import { TableCellOptions, TableCellVariant } from "./table.js";
+import { AlertOptions, AlertStatus, StatusOptions, StatusValue, ToastOptions, ToastStatus, toastDefaults } from "./status.js";
+export { type AlertOptions, type AlertStatus, type BadgeOptions, type BadgeSize, type BadgeVariant, type ButtonOptions, type ButtonSize, type ButtonVariant, type CardOptions, type CardVariant, type ComboboxOption, type ComboboxOptions, type Placement, type SelectOption, type SelectOptions, type StatusOptions, type StatusValue, type TableCellOptions, type TableCellVariant, type ToastOptions, type ToastStatus, badgeDefaults, buttonDefaults, cardDefaults, toastDefaults };

package/dist/index.js

@@ -0,0 +1,5 @@
+import { badgeDefaults } from "./badge.js";
+import { buttonDefaults } from "./button.js";
+import { cardDefaults } from "./card.js";
+import { toastDefaults } from "./status.js";
+export { badgeDefaults, buttonDefaults, cardDefaults, toastDefaults };

package/dist/placement.d.ts

@@ -0,0 +1,3 @@
+//#region src/placement.d.ts
+export type Placement = "top" | "top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end";
+//#endregion

package/dist/select.d.ts

@@ -0,0 +1,22 @@
+import { Placement } from "./placement.js";
+//#region src/select.d.ts
+export type SelectOption = {
+  label: string;
+  value: string;
+  disabled?: boolean;
+};
+export type SelectOptions = {
+  id: string;
+  label: string;
+  name?: string;
+  placeholder?: string;
+  options: SelectOption[];
+  value?: string;
+  disabled?: boolean;
+  invalid?: boolean;
+  required?: boolean;
+  placement?: Placement;
+  onValueChange: (value: string) => void;
+  onOpenChange?: (open: boolean) => void;
+};
+//#endregion

package/dist/status.d.ts

@@ -0,0 +1,17 @@
+//#region src/status.d.ts
+export type StatusValue = "success" | "danger" | "info";
+export type StatusOptions = {
+  status?: StatusValue;
+};
+export type AlertStatus = "danger" | "info";
+export type AlertOptions = {
+  status?: AlertStatus;
+};
+export type ToastStatus = "success";
+export type ToastOptions = {
+  status?: ToastStatus;
+};
+export declare const toastDefaults: {
+  readonly status: "success";
+};
+//#endregion

package/dist/status.js

@@ -0,0 +1,4 @@
+//#region src/status.ts
+const toastDefaults = { status: "success" };
+//#endregion
+export { toastDefaults };

package/dist/table.d.ts

@@ -0,0 +1,6 @@
+//#region src/table.d.ts
+export type TableCellVariant = "code" | "number";
+export type TableCellOptions = {
+  variant?: TableCellVariant;
+};
+//#endregion

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@simple-base/contracts",
+  "version": "0.1.0",
+  "license": "MIT",
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./badge": {
+      "types": "./dist/badge.d.ts",
+      "import": "./dist/badge.js"
+    },
+    "./button": {
+      "types": "./dist/button.d.ts",
+      "import": "./dist/button.js"
+    },
+    "./card": {
+      "types": "./dist/card.d.ts",
+      "import": "./dist/card.js"
+    },
+    "./combobox": {
+      "types": "./dist/combobox.d.ts",
+      "import": "./dist/combobox.js"
+    },
+    "./placement": {
+      "types": "./dist/placement.d.ts",
+      "import": "./dist/placement.js"
+    },
+    "./select": {
+      "types": "./dist/select.d.ts",
+      "import": "./dist/select.js"
+    },
+    "./status": {
+      "types": "./dist/status.d.ts",
+      "import": "./dist/status.js"
+    },
+    "./table": {
+      "types": "./dist/table.d.ts",
+      "import": "./dist/table.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@types/node": "^25.8.0",
+    "tsdown": "^0.23.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch --no-clean",
+    "typecheck": "tsc --noEmit"
+  }
+}