@ladder-ui/field 0.2.0

package/dist/field.css

@@ -0,0 +1,47 @@
+@layer components {
+  .lui-field {
+    display: flex;
+    flex-direction: column;
+    gap: var(--lui-field-gap);
+  }
+  .lui-field--horizontal {
+    flex-direction: row;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: var(--lui-field-gap);
+  }
+  .lui-field[data-disabled=true] .lui-field-label,
+  .lui-field[data-disabled=true] .lui-field-description {
+    opacity: 0.5;
+  }
+  .lui-field[data-invalid=true] .lui-field-label {
+    color: var(--lui-field-error-color);
+  }
+  .lui-field-label {
+    display: block;
+    color: var(--lui-field-label-color);
+    font-family: var(--lui-font-family);
+    font-size: var(--lui-field-label-size);
+    font-weight: 500;
+    line-height: 1.4;
+  }
+  .lui-field-description {
+    margin: 0;
+    color: var(--lui-field-description-color);
+    font-family: var(--lui-font-family);
+    font-size: var(--lui-field-description-size);
+    line-height: 1.5;
+  }
+  .lui-field-error {
+    margin: 0;
+    color: var(--lui-field-error-color);
+    font-family: var(--lui-font-family);
+    font-size: var(--lui-field-error-size);
+    line-height: 1.5;
+  }
+  .lui-field-group {
+    display: flex;
+    flex-direction: column;
+    gap: var(--lui-field-group-gap);
+  }
+}

package/dist/field.d.ts

@@ -0,0 +1,97 @@
+import type { HTMLAttributes, Ref } from "react";
+import { type LabelProps } from "@ladder-ui/label";
+export interface FieldProps extends HTMLAttributes<HTMLDivElement> {
+    /** React 19 ref — points to the wrapper `<div>` */
+    ref?: Ref<HTMLDivElement>;
+    /**
+     * Layout orientation.
+     * - `"vertical"` (default): label stacked above the control
+     * - `"horizontal"`: label and control side by side
+     */
+    orientation?: "vertical" | "horizontal";
+}
+/**
+ * Field — semantic wrapper for a single form field.
+ *
+ * Provides layout (label + control + description + error) and propagates
+ * disabled/invalid state to child components via `data-disabled` / `data-invalid`
+ * HTML attributes, which are picked up by CSS selectors.
+ *
+ * Usage:
+ * ```tsx
+ * <Field>
+ *   <FieldLabel htmlFor="email">Email</FieldLabel>
+ *   <Input id="email" type="email" />
+ *   <FieldDescription>We'll never share your email.</FieldDescription>
+ * </Field>
+ *
+ * <Field data-invalid="true">
+ *   <FieldLabel htmlFor="user">Username</FieldLabel>
+ *   <Input id="user" status="error" aria-invalid="true" />
+ *   <FieldError>Username already taken.</FieldError>
+ * </Field>
+ * ```
+ */
+export declare function Field({ ref, className, orientation, ...props }: FieldProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Field {
+    var displayName: string;
+}
+export interface FieldLabelProps extends LabelProps {
+    /**
+     * React 19 ref — points to the `<label>` element.
+     * Inherited from LabelProps.
+     */
+    ref?: Ref<HTMLLabelElement>;
+}
+/**
+ * FieldLabel — a `Label` scoped to a `Field` compound component.
+ *
+ * Wraps `@ladder-ui/label`'s `Label` and adds the `lui-field-label` class so
+ * the parent `Field` can apply context-aware styles:
+ *   - Dims when `<Field data-disabled="true">` is set
+ *   - Turns error-color when `<Field data-invalid="true">` is set
+ *
+ * For labels **outside a Field** context, use `Label` from `@ladder-ui/label`
+ * directly — it provides the same accessible `<label>` element with styling
+ * but without the Field-specific context.
+ */
+export declare function FieldLabel({ ref, className, ...props }: FieldLabelProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace FieldLabel {
+    var displayName: string;
+}
+export interface FieldDescriptionProps extends HTMLAttributes<HTMLParagraphElement> {
+    /** React 19 ref — points to the `<p>` element */
+    ref?: Ref<HTMLParagraphElement>;
+}
+/**
+ * FieldDescription — muted helper text rendered below the control.
+ * Dims automatically when the parent `<Field>` has `data-disabled="true"`.
+ */
+export declare function FieldDescription({ ref, className, ...props }: FieldDescriptionProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace FieldDescription {
+    var displayName: string;
+}
+export interface FieldErrorProps extends HTMLAttributes<HTMLParagraphElement> {
+    /** React 19 ref — points to the `<p>` element */
+    ref?: Ref<HTMLParagraphElement>;
+}
+/**
+ * FieldError — error text rendered below the control.
+ * Has `role="alert"` for live-region announcements.
+ * Only meaningful when the parent `<Field>` has `data-invalid="true"`.
+ */
+export declare function FieldError({ ref, className, ...props }: FieldErrorProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace FieldError {
+    var displayName: string;
+}
+export interface FieldGroupProps extends HTMLAttributes<HTMLDivElement> {
+    /** React 19 ref — points to the wrapper `<div>` */
+    ref?: Ref<HTMLDivElement>;
+}
+/**
+ * FieldGroup — groups multiple `<Field>` elements with a consistent vertical gap.
+ */
+export declare function FieldGroup({ ref, className, ...props }: FieldGroupProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace FieldGroup {
+    var displayName: string;
+}

package/dist/field.vars.css

@@ -0,0 +1,15 @@
+@charset "UTF-8";
+:root {
+  /* Layout */
+  --lui-field-gap: 0.375rem;
+  --lui-field-group-gap: 1rem;
+  /* Label — field-specific overrides of @ladder-ui/label base tokens */
+  --lui-field-label-color: var(--lui-surface-text);
+  --lui-field-label-size: var(--lui-font-size-sm);
+  /* Description */
+  --lui-field-description-color: color-mix(in srgb, var(--lui-surface-text) 60%, transparent);
+  --lui-field-description-size: var(--lui-font-size-xs);
+  /* Error */
+  --lui-field-error-color: var(--lui-error);
+  --lui-field-error-size: var(--lui-font-size-xs);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Field, FieldLabel, FieldDescription, FieldError, FieldGroup } from "./field";
+export type { FieldProps, FieldLabelProps, FieldDescriptionProps, FieldErrorProps, FieldGroupProps, } from "./field";

package/dist/index.js

@@ -0,0 +1,78 @@
+'use strict';
+
+var jsxRuntime = require('react/jsx-runtime');
+var concatClassNames = require('@ladder-ui/core/concatClassNames');
+var label = require('@ladder-ui/label');
+
+/**
+ * Field — semantic wrapper for a single form field.
+ *
+ * Provides layout (label + control + description + error) and propagates
+ * disabled/invalid state to child components via `data-disabled` / `data-invalid`
+ * HTML attributes, which are picked up by CSS selectors.
+ *
+ * Usage:
+ * ```tsx
+ * <Field>
+ *   <FieldLabel htmlFor="email">Email</FieldLabel>
+ *   <Input id="email" type="email" />
+ *   <FieldDescription>We'll never share your email.</FieldDescription>
+ * </Field>
+ *
+ * <Field data-invalid="true">
+ *   <FieldLabel htmlFor="user">Username</FieldLabel>
+ *   <Input id="user" status="error" aria-invalid="true" />
+ *   <FieldError>Username already taken.</FieldError>
+ * </Field>
+ * ```
+ */
+function Field({ ref, className, orientation = "vertical", ...props }) {
+    return (jsxRuntime.jsx("div", { ref: ref, className: concatClassNames("lui-field", orientation === "horizontal" && "lui-field--horizontal", className), ...props }));
+}
+Field.displayName = "Field";
+/**
+ * FieldLabel — a `Label` scoped to a `Field` compound component.
+ *
+ * Wraps `@ladder-ui/label`'s `Label` and adds the `lui-field-label` class so
+ * the parent `Field` can apply context-aware styles:
+ *   - Dims when `<Field data-disabled="true">` is set
+ *   - Turns error-color when `<Field data-invalid="true">` is set
+ *
+ * For labels **outside a Field** context, use `Label` from `@ladder-ui/label`
+ * directly — it provides the same accessible `<label>` element with styling
+ * but without the Field-specific context.
+ */
+function FieldLabel({ ref, className, ...props }) {
+    return (jsxRuntime.jsx(label.Label, { ref: ref, className: concatClassNames("lui-field-label", className), ...props }));
+}
+FieldLabel.displayName = "FieldLabel";
+/**
+ * FieldDescription — muted helper text rendered below the control.
+ * Dims automatically when the parent `<Field>` has `data-disabled="true"`.
+ */
+function FieldDescription({ ref, className, ...props }) {
+    return (jsxRuntime.jsx("p", { ref: ref, className: concatClassNames("lui-field-description", className), ...props }));
+}
+FieldDescription.displayName = "FieldDescription";
+/**
+ * FieldError — error text rendered below the control.
+ * Has `role="alert"` for live-region announcements.
+ * Only meaningful when the parent `<Field>` has `data-invalid="true"`.
+ */
+function FieldError({ ref, className, ...props }) {
+    return (jsxRuntime.jsx("p", { ref: ref, role: "alert", className: concatClassNames("lui-field-error", className), ...props }));
+}
+FieldError.displayName = "FieldError";
+/**
+ * FieldGroup — groups multiple `<Field>` elements with a consistent vertical gap.
+ */
+function FieldGroup({ ref, className, ...props }) {
+    return (jsxRuntime.jsx("div", { ref: ref, className: concatClassNames("lui-field-group", className), ...props }));
+}
+FieldGroup.displayName = "FieldGroup";
+
+exports.Field = Field;
+exports.FieldDescription = FieldDescription;
+exports.FieldError = FieldError;
+exports.FieldGroup = FieldGroup;
+exports.FieldLabel = FieldLabel;

package/dist/index.mjs

@@ -0,0 +1,72 @@
+import { jsx } from 'react/jsx-runtime';
+import concatClassNames from '@ladder-ui/core/concatClassNames';
+import { Label } from '@ladder-ui/label';
+
+/**
+ * Field — semantic wrapper for a single form field.
+ *
+ * Provides layout (label + control + description + error) and propagates
+ * disabled/invalid state to child components via `data-disabled` / `data-invalid`
+ * HTML attributes, which are picked up by CSS selectors.
+ *
+ * Usage:
+ * ```tsx
+ * <Field>
+ *   <FieldLabel htmlFor="email">Email</FieldLabel>
+ *   <Input id="email" type="email" />
+ *   <FieldDescription>We'll never share your email.</FieldDescription>
+ * </Field>
+ *
+ * <Field data-invalid="true">
+ *   <FieldLabel htmlFor="user">Username</FieldLabel>
+ *   <Input id="user" status="error" aria-invalid="true" />
+ *   <FieldError>Username already taken.</FieldError>
+ * </Field>
+ * ```
+ */
+function Field({ ref, className, orientation = "vertical", ...props }) {
+    return (jsx("div", { ref: ref, className: concatClassNames("lui-field", orientation === "horizontal" && "lui-field--horizontal", className), ...props }));
+}
+Field.displayName = "Field";
+/**
+ * FieldLabel — a `Label` scoped to a `Field` compound component.
+ *
+ * Wraps `@ladder-ui/label`'s `Label` and adds the `lui-field-label` class so
+ * the parent `Field` can apply context-aware styles:
+ *   - Dims when `<Field data-disabled="true">` is set
+ *   - Turns error-color when `<Field data-invalid="true">` is set
+ *
+ * For labels **outside a Field** context, use `Label` from `@ladder-ui/label`
+ * directly — it provides the same accessible `<label>` element with styling
+ * but without the Field-specific context.
+ */
+function FieldLabel({ ref, className, ...props }) {
+    return (jsx(Label, { ref: ref, className: concatClassNames("lui-field-label", className), ...props }));
+}
+FieldLabel.displayName = "FieldLabel";
+/**
+ * FieldDescription — muted helper text rendered below the control.
+ * Dims automatically when the parent `<Field>` has `data-disabled="true"`.
+ */
+function FieldDescription({ ref, className, ...props }) {
+    return (jsx("p", { ref: ref, className: concatClassNames("lui-field-description", className), ...props }));
+}
+FieldDescription.displayName = "FieldDescription";
+/**
+ * FieldError — error text rendered below the control.
+ * Has `role="alert"` for live-region announcements.
+ * Only meaningful when the parent `<Field>` has `data-invalid="true"`.
+ */
+function FieldError({ ref, className, ...props }) {
+    return (jsx("p", { ref: ref, role: "alert", className: concatClassNames("lui-field-error", className), ...props }));
+}
+FieldError.displayName = "FieldError";
+/**
+ * FieldGroup — groups multiple `<Field>` elements with a consistent vertical gap.
+ */
+function FieldGroup({ ref, className, ...props }) {
+    return (jsx("div", { ref: ref, className: concatClassNames("lui-field-group", className), ...props }));
+}
+FieldGroup.displayName = "FieldGroup";
+
+export { Field, FieldDescription, FieldError, FieldGroup, FieldLabel };

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@ladder-ui/field",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./*.css": "./dist/*.css",
+    "./styles/*.css": "./dist/*.css"
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "nodejs",
+    "react",
+    "ui",
+    "components",
+    "library",
+    "field",
+    "form",
+    "label"
+  ],
+  "author": "Ivan Avila <ivelaval@gmail.com> - https://www.vennet.dev",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/ivelaval/ladder-ui.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ivelaval/ladder-ui/issues"
+  },
+  "homepage": "https://github.com/ivelaval/ladder-ui#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "^11.1.6",
+    "@types/react": "^19.0.0",
+    "rollup": "^4.59.0",
+    "rollup-plugin-postcss": "^4.0.2",
+    "sass": "^1.90.0",
+    "tslib": "^2.6.2",
+    "typescript": "^5.3.3",
+    "@ladder-ui/core": "0.2.0",
+    "@ladder-ui/label": "0.2.0"
+  },
+  "peerDependencies": {
+    "@ladder-ui/core": ">=0.0.0",
+    "@ladder-ui/label": ">=0.0.0",
+    "react": ">=18.0.0"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "scripts": {
+    "build": "pnpm clean && rollup -c",
+    "dev": "rollup -c -w",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "type-check": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}