@kubuild/components 0.0.1

package/dist/traits.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Trait metadata (STORA-210).
+ *
+ * A **trait** is a *functional* prop — it carries behavior, semantics, or
+ * identity rather than pure visual styling. Examples: `href`, `target`, `alt`,
+ * `title`, `placeholder`, `aria-label`, and a custom `id`.
+ *
+ * Traits are deliberately separated from styling concerns:
+ * - Styling lives in `defaultStyles` (a `ResponsiveStyles` object) and is
+ *   applied via the style abstraction, never as raw HTML attributes.
+ * - Traits describe the *semantic/behavioral* surface of a component and map
+ *   to real HTML attributes at render time (see `attribute`).
+ *
+ * This module defines the trait metadata shape plus a set of reusable trait
+ * factories so every component definition can declare its traits with clear
+ * data types and default values — satisfying STORA-210's acceptance criteria.
+ */
+/** The primitive data types a trait value can take. */
+export type TraitType = 'string' | 'number' | 'boolean' | 'select';
+/** A constrained choice for `select`-typed traits. */
+export interface TraitOption {
+    label: string;
+    value: unknown;
+}
+/**
+ * Logical grouping used to organize traits in an inspector UI. Kept as a
+ * closed union so hosts can render a stable, ordered set of trait sections.
+ */
+export type TraitGroup = 'link' | 'media' | 'form' | 'accessibility' | 'identity' | 'behavior' | 'semantic';
+/** Ordered display order for trait groups in an inspector. */
+export declare const TRAIT_GROUP_ORDER: TraitGroup[];
+/** Human-readable labels for each trait group. */
+export declare const TRAIT_GROUP_LABELS: Record<TraitGroup, string>;
+/**
+ * Metadata describing a single functional trait on a component.
+ *
+ * `name` is the prop key on the node's `props` object; `attribute` is the HTML
+ * attribute it maps to at render time (when they differ, e.g. `name` → `id`).
+ */
+export interface ComponentTraitDefinition {
+    /** Prop key on the node's `props` object (e.g. `'href'`, `'alt'`). */
+    name: string;
+    /** Human-readable label shown in the inspector. */
+    label: string;
+    /** Data type of the trait value. */
+    type: TraitType;
+    /** Default value applied when the trait is not set. */
+    defaultValue?: unknown;
+    /** Constrained choices for `select`-typed traits. */
+    options?: TraitOption[];
+    /** Short description of the trait's purpose. */
+    description?: string;
+    /** The HTML attribute this trait maps to at render time (e.g. `'href'`). */
+    attribute?: string;
+    /** Whether the trait must be present for the component to be valid. */
+    required?: boolean;
+    /** Logical grouping for inspector organization. */
+    group?: TraitGroup;
+}
+/** Convenience alias for a list of trait definitions. */
+export type ComponentTraits = ComponentTraitDefinition[];
+/** `href` — the destination URL for links, buttons, and form actions. */
+export declare function hrefTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `target` — where the linked resource opens (`_self`, `_blank`, ...). */
+export declare function targetTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `rel` — relationship between the current document and the linked resource. */
+export declare function relTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `alt` — alternative text for media, required for accessibility. */
+export declare function altTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `title` — advisory title shown on hover / used as a fallback label. */
+export declare function titleTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `placeholder` — hint text shown inside an empty form control. */
+export declare function placeholderTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `aria-label` — accessible name for elements without visible text. */
+export declare function ariaLabelTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `id` — a custom, document-unique identifier for the element. */
+export declare function idTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `name` — the form field name submitted with the form data. */
+export declare function fieldNameTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `required` — whether the form field must be filled before submission. */
+export declare function requiredTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `disabled` — whether the control is non-interactive. */
+export declare function disabledTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `readOnly` — whether the control value can be changed by the user. */
+export declare function readOnlyTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `src` — the source URL for media (image, video). */
+export declare function srcTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `poster` — a preview image shown before a video plays. */
+export declare function posterTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `controls` — whether native media controls are shown. */
+export declare function controlsTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `autoplay` — whether media starts playing automatically. */
+export declare function autoplayTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `loop` — whether media restarts from the beginning when it ends. */
+export declare function loopTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `muted` — whether media starts with sound muted. */
+export declare function mutedTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `cite` — the source URL for a blockquote. */
+export declare function citeTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `loading` — native lazy/eager loading hint for images (STORA-213). */
+export declare function loadingTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `action` — the URL a form submits to. */
+export declare function actionTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `method` — the HTTP method a form uses to submit. */
+export declare function methodTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `autoComplete` — whether the browser may autofill the form. */
+export declare function autoCompleteTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `value` — the value submitted for a checkbox/radio when checked. */
+export declare function valueTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `defaultChecked` — whether a checkbox/radio starts checked. */
+export declare function defaultCheckedTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `defaultValue` — the initial value of a form control. */
+export declare function defaultValueTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `rows` — the visible number of lines in a textarea. */
+export declare function rowsTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `colSpan` — the number of columns a table cell spans. */
+export declare function colSpanTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `rowSpan` — the number of rows a table cell spans. */
+export declare function rowSpanTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `tag` — the semantic HTML tag a component renders as (e.g. `ul`/`ol`, `td`/`th`). */
+export declare function tagTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `type` — the input type of a form control (text, email, number, ...). */
+export declare function inputTypeTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/** `buttonType` — the button's form behavior (`button`, `submit`, `reset`). */
+export declare function buttonTypeTrait(overrides?: Partial<ComponentTraitDefinition>): ComponentTraitDefinition;
+/**
+ * Sort a component's traits into a stable, inspector-friendly order:
+ * identity first, then the remaining groups in `TRAIT_GROUP_ORDER`, with
+ * ungrouped traits last. Preserves relative order within each group.
+ */
+export declare function sortTraits(traits: ComponentTraits): ComponentTraits;
+/**
+ * Collect the union of all trait names declared across a set of component
+ * definitions. Useful for building a global trait catalog / search index.
+ */
+export declare function collectTraitNames(traitsList: ComponentTraits[]): string[];
+//# sourceMappingURL=traits.d.ts.map

package/dist/traits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"traits.d.ts","sourceRoot":"","sources":["../src/traits.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@kubuild/components",
+  "version": "0.0.1",
+  "description": "Component registry and base definitions for KUBUILD",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && tsc --emitDeclarationOnly",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run",
+    "prepublishOnly": "pnpm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kustora/kubuild.git"
+  },
+  "keywords": [
+    "page-builder",
+    "visual-editor",
+    "low-code",
+    "website-builder",
+    "stora",
+    "kubuild"
+  ],
+  "author": "KUBUILD",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/kustora/kubuild/issues"
+  },
+  "homepage": "https://github.com/kustora/kubuild#readme",
+  "dependencies": {
+    "@kubuild/core": "workspace:*",
+    "@kubuild/schema": "workspace:*"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.6",
+    "typescript": "^6.0.0",
+    "vitest": "^3.0.5"
+  }
+}