@teseor/css 1.7.0 → 1.9.0

package/src/{04-components → components}/forms/checkbox-group/index.scss

@@ -1,26 +1,42 @@
-@use '../../../00-config/tokens/variables' as t;
+@use '../../../config/tokens/variables' as t;
 
 // @component checkbox-group
 // @element fieldset
 
 @layer components.tokens {
   .checkbox-group {
+    --_leading-tight-sm: var(--ui-leading-tight-sm, var(--ui-row-1, #{t.$leading-tight-sm}));
+    --_row-1: var(--ui-row-1, #{t.$row-1});
+    --_opacity-disabled: var(--ui-opacity-disabled, #{t.$opacity-disabled});
+    --_space-2: var(--ui-space-2, #{t.$space-2});
+    // @desc Spacing
     --_spacing: var(--ui-checkbox-group-spacing, var(--ui-space-1, #{t.$space-1}));
+    // @desc Legend size
     --_legend-size: var(--ui-checkbox-group-legend-size, var(--ui-font-size-sm, #{t.$font-size-sm}));
+    // @desc Legend weight
     --_legend-weight: var(--ui-checkbox-group-legend-weight, var(--ui-weight-medium, #{t.$weight-medium}));
+    // @desc Legend color
     --_legend-color: var(--ui-checkbox-group-legend-color, var(--ui-color-text, #{t.$color-text}));
+    // @desc Legend spacing
     --_legend-spacing: var(--ui-checkbox-group-legend-spacing, var(--ui-space-1, #{t.$space-1}));
+    // @desc Item gap between children
     --_item-gap: var(--ui-checkbox-group-item-gap, var(--ui-space-1, #{t.$space-1}));
   }
 
+  // @modifier boolean compact
   .checkbox-group--compact {
+    // @desc Spacing compact
     --_spacing: var(--ui-checkbox-group-spacing-compact, 0);
+    // @desc Legend spacing compact
     --_legend-spacing: var(--ui-checkbox-group-legend-spacing-compact, 0);
+    // @desc Item gap compact
     --_item-gap: var(--ui-checkbox-group-item-gap-compact, 0);
   }
 
   // @modifier state
+  // @modifier boolean error
   .checkbox-group--error {
+    // @desc Error color
     --_legend-color: var(--ui-checkbox-group-error-color, var(--ui-color-danger, #{t.$color-danger}));
   }
 }
@@ -43,7 +59,7 @@
 
     font-size: var(--_legend-size);
     font-weight: var(--_legend-weight);
-    line-height: var(--ui-leading-tight-sm, var(--ui-row-1, #{t.$leading-tight-sm}));
+    line-height: var(--_leading-tight-sm);
     color: var(--_legend-color);
   }
 
@@ -58,27 +74,28 @@
     align-items: center;
     gap: var(--_item-gap);
 
-    line-height: var(--ui-row-1, #{t.$row-1});
+    line-height: var(--_row-1);
 
     cursor: pointer;
   }
 
   .checkbox-group__item:has(:disabled) {
-    opacity: 0.5;
+    opacity: var(--_opacity-disabled);
     cursor: not-allowed;
   }
 
   // Horizontal layout
+  // @modifier boolean horizontal
   .checkbox-group--horizontal > .checkbox-group__items {
     flex-direction: row;
     flex-wrap: wrap;
-    gap: var(--ui-space-2, #{t.$space-2});
+    gap: var(--_space-2);
   }
 
   // Disabled group
   .checkbox-group:disabled,
   .checkbox-group[aria-disabled='true'] {
-    opacity: 0.5;
+    opacity: var(--_opacity-disabled);
     cursor: not-allowed;
   }
 }

package/src/components/forms/field/field.api.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "Auto-generated from index.scss annotations. Do not edit manually — run: pnpm generate:api",
+  "name": "field",
+  "element": "div",
+  "modifiers": {
+    "horizontal": {
+      "type": "boolean"
+    }
+  },
+  "elements": {
+    "control": {},
+    "label": {}
+  },
+  "cssVars": [
+    {
+      "name": "--ui-field-gap",
+      "default": "0",
+      "description": "Gap between children"
+    }
+  ]
+}

package/src/components/forms/field/field.docs.json

@@ -0,0 +1,190 @@
+{
+  "id": "field",
+  "type": "component",
+  "title": "Field",
+  "description": "Form field wrapper that combines label, control, helper text, and error message.",
+  "api": "./field.api.json",
+  "sections": [
+    {
+      "title": "Default",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "div",
+              "class": "ui-field",
+              "children": [
+                {
+                  "tag": "label",
+                  "class": "ui-label",
+                  "text": "Email",
+                  "attrs": { "for": "email" }
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-field__control",
+                  "children": [
+                    {
+                      "tag": "input",
+                      "class": "ui-input",
+                      "attrs": { "type": "email", "id": "email", "placeholder": "Enter email" }
+                    }
+                  ]
+                }
+              ]
+            }
+          ],
+          "code": "<div class=\"ui-field\">\n  <label class=\"ui-label\" for=\"email\">Email</label>\n  <div class=\"ui-field__control\">\n    <input type=\"email\" id=\"email\" class=\"ui-input\">\n  </div>\n</div>"
+        }
+      ]
+    },
+    {
+      "title": "With Helper Text",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "div",
+              "class": "ui-field",
+              "children": [
+                {
+                  "tag": "label",
+                  "class": "ui-label",
+                  "text": "Password",
+                  "attrs": { "for": "password" }
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-field__control",
+                  "children": [
+                    {
+                      "tag": "input",
+                      "class": "ui-input",
+                      "attrs": { "type": "password", "id": "password" }
+                    },
+                    {
+                      "tag": "span",
+                      "class": "ui-form-helper",
+                      "text": "Must be at least 8 characters"
+                    }
+                  ]
+                }
+              ]
+            }
+          ],
+          "code": "<div class=\"ui-field\">\n  <label class=\"ui-label\" for=\"password\">Password</label>\n  <div class=\"ui-field__control\">\n    <input type=\"password\" id=\"password\" class=\"ui-input\">\n    <span class=\"ui-form-helper\">Must be at least 8 characters</span>\n  </div>\n</div>"
+        }
+      ]
+    },
+    {
+      "title": "With Error",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "div",
+              "class": "ui-field",
+              "children": [
+                {
+                  "tag": "label",
+                  "class": "ui-label",
+                  "text": "Username",
+                  "attrs": { "for": "username" }
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-field__control",
+                  "children": [
+                    {
+                      "tag": "input",
+                      "class": "ui-input ui-input--error",
+                      "attrs": { "type": "text", "id": "username", "value": "ab" }
+                    },
+                    {
+                      "tag": "span",
+                      "class": "ui-form-error",
+                      "text": "Username must be at least 3 characters"
+                    }
+                  ]
+                }
+              ]
+            }
+          ],
+          "code": "<div class=\"ui-field\">\n  <label class=\"ui-label\" for=\"username\">Username</label>\n  <div class=\"ui-field__control\">\n    <input type=\"text\" id=\"username\" class=\"ui-input ui-input--error\">\n    <span class=\"ui-form-error\">Username must be at least 3 characters</span>\n  </div>\n</div>"
+        }
+      ]
+    },
+    {
+      "title": "Horizontal Layout",
+      "description": "Label beside control for wider forms",
+      "api": "./field.api.json",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "div",
+              "class": "ui-field ui-field--horizontal",
+              "children": [
+                {
+                  "tag": "label",
+                  "class": "ui-label ui-field__label",
+                  "text": "Full Name",
+                  "attrs": { "for": "name" }
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-field__control",
+                  "children": [
+                    {
+                      "tag": "input",
+                      "class": "ui-input",
+                      "attrs": { "type": "text", "id": "name" }
+                    },
+                    { "tag": "span", "class": "ui-form-helper", "text": "As it appears on your ID" }
+                  ]
+                }
+              ]
+            }
+          ],
+          "code": "<div class=\"ui-field ui-field--horizontal\">\n  <label class=\"ui-label ui-field__label\" for=\"name\">Full Name</label>\n  <div class=\"ui-field__control\">\n    <input type=\"text\" id=\"name\" class=\"ui-input\">\n    <span class=\"ui-form-helper\">As it appears on your ID</span>\n  </div>\n</div>"
+        }
+      ]
+    },
+    {
+      "title": "Required Field",
+      "examples": [
+        {
+          "items": [
+            {
+              "tag": "div",
+              "class": "ui-field",
+              "children": [
+                {
+                  "tag": "label",
+                  "class": "ui-label ui-label--required",
+                  "text": "Required Field",
+                  "attrs": { "for": "req" }
+                },
+                {
+                  "tag": "div",
+                  "class": "ui-field__control",
+                  "children": [
+                    {
+                      "tag": "input",
+                      "class": "ui-input",
+                      "attrs": { "type": "text", "id": "req", "required": "" }
+                    }
+                  ]
+                }
+              ]
+            }
+          ],
+          "code": "<div class=\"ui-field\">\n  <label class=\"ui-label ui-label--required\" for=\"req\">Required Field</label>\n  <div class=\"ui-field__control\">\n    <input type=\"text\" id=\"req\" class=\"ui-input\" required>\n  </div>\n</div>"
+        }
+      ]
+    }
+  ],
+  "customization": [
+    { "token": "--ui-field-gap", "default": "0", "description": "Gap between field elements" }
+  ]
+}

package/src/{04-components → components}/forms/field/index.scss

@@ -1,10 +1,13 @@
-@use '../../../00-config/tokens/variables' as t;
+@use '../../../config/tokens/variables' as t;
+// @component field
+// @element div
 
 // Field - form field wrapper
 // Combines label, control, helper text, and error message
 
 @layer components.tokens {
   .field {
+    // @desc Gap between children
     --_gap: var(--ui-field-gap, 0);
   }
 }
@@ -23,6 +26,7 @@
   }
 
   // Horizontal layout variant
+  // @modifier boolean horizontal
   .field--horizontal {
     flex-direction: row;
     flex-wrap: wrap;

package/src/components/forms/fieldset/fieldset.api.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "Auto-generated from index.scss annotations. Do not edit manually — run: pnpm generate:api",
+  "name": "fieldset",
+  "element": "fieldset",
+  "modifiers": {
+    "compact": {
+      "type": "boolean"
+    },
+    "bordered": {
+      "type": "boolean"
+    }
+  },
+  "elements": {
+    "legend": {}
+  },
+  "cssVars": [
+    {
+      "name": "--ui-fieldset-spacing",
+      "default": "var(--ui-space-2)",
+      "description": "Spacing"
+    },
+    {
+      "name": "--ui-fieldset-border-color",
+      "default": "var(--ui-color-border)",
+      "description": "Border color"
+    },
+    {
+      "name": "--ui-fieldset-border-width",
+      "default": "var(--ui-border-width-sm)",
+      "description": "Border thickness"
+    },
+    {
+      "name": "--ui-fieldset-border-radius",
+      "default": "var(--ui-radius-md)",
+      "description": "Border radius"
+    },
+    {
+      "name": "--ui-fieldset-padding",
+      "default": "var(--ui-space-2)",
+      "description": "Padding on all sides"
+    },
+    {
+      "name": "--ui-fieldset-legend-size",
+      "default": "var(--ui-font-size-sm)",
+      "description": "Legend size"
+    },
+    {
+      "name": "--ui-fieldset-legend-weight",
+      "default": "var(--ui-weight-medium)",
+      "description": "Legend weight"
+    },
+    {
+      "name": "--ui-fieldset-legend-color",
+      "default": "var(--ui-color-text)",
+      "description": "Legend color"
+    },
+    {
+      "name": "--ui-fieldset-spacing-compact",
+      "default": "var(--ui-space-1)",
+      "description": "Spacing compact"
+    },
+    {
+      "name": "--ui-fieldset-padding-compact",
+      "default": "var(--ui-space-1)",
+      "description": "Padding compact"
+    }
+  ]
+}

package/src/{04-components → components}/forms/fieldset/index.scss

@@ -1,22 +1,38 @@
-@use '../../../00-config/tokens/variables' as t;
+@use '../../../config/tokens/variables' as t;
+// @component fieldset
+// @element fieldset
 
 // Fieldset - groups related form fields
 // Resets native fieldset chrome, provides consistent spacing and optional border
 
 @layer components.tokens {
   .fieldset {
+    --_leading-tight-sm: var(--ui-leading-tight-sm, var(--ui-row-1, #{t.$leading-tight-sm}));
+    --_space-half: var(--ui-space-half, #{t.$space-0});
+    --_opacity-disabled: var(--ui-opacity-disabled, #{t.$opacity-disabled});
+    // @desc Spacing
     --_spacing: var(--ui-fieldset-spacing, var(--ui-space-2, #{t.$space-2}));
+    // @desc Border color
     --_border-color: var(--ui-fieldset-border-color, var(--ui-color-border, #{t.$color-border}));
+    // @desc Border thickness
     --_border-width: var(--ui-fieldset-border-width, var(--ui-border-width-sm, #{t.$border-width-sm}));
+    // @desc Border radius
     --_border-radius: var(--ui-fieldset-border-radius, var(--ui-radius-md, #{t.$radius-md}));
+    // @desc Padding on all sides
     --_padding: var(--ui-fieldset-padding, var(--ui-space-2, #{t.$space-2}));
+    // @desc Legend size
     --_legend-size: var(--ui-fieldset-legend-size, var(--ui-font-size-sm, #{t.$font-size-sm}));
+    // @desc Legend weight
     --_legend-weight: var(--ui-fieldset-legend-weight, var(--ui-weight-medium, #{t.$weight-medium}));
+    // @desc Legend color
     --_legend-color: var(--ui-fieldset-legend-color, var(--ui-color-text, #{t.$color-text}));
   }
 
+  // @modifier boolean compact
   .fieldset--compact {
+    // @desc Spacing compact
     --_spacing: var(--ui-fieldset-spacing-compact, var(--ui-space-1, #{t.$space-1}));
+    // @desc Padding compact
     --_padding: var(--ui-fieldset-padding-compact, var(--ui-space-1, #{t.$space-1}));
   }
 }
@@ -40,12 +56,13 @@
 
     font-size: var(--_legend-size);
     font-weight: var(--_legend-weight);
-    line-height: var(--ui-leading-tight-sm, var(--ui-row-1, #{t.$leading-tight-sm}));
+    line-height: var(--_leading-tight-sm);
     color: var(--_legend-color);
   }
 
   // Bordered variant - visible border wrapping the group
   // Legend absorbs the top border; compensate bottom border to keep grid rhythm
+  // @modifier boolean bordered
   .fieldset--bordered {
     padding: var(--_padding);
     padding-block-end: calc(var(--_padding) - var(--_border-width));
@@ -56,14 +73,14 @@
 
   .fieldset--bordered > .fieldset__legend {
     inline-size: auto;
-    padding-inline: var(--ui-space-half, #{t.$space-0});
-    margin-inline-start: calc(-1 * var(--ui-space-half, #{t.$space-0}));
+    padding-inline: var(--_space-half);
+    margin-inline-start: calc(-1 * var(--_space-half));
   }
 
   // Disabled state - fieldset[disabled] natively disables children
   .fieldset:disabled,
   .fieldset[aria-disabled='true'] {
-    opacity: 0.5;
+    opacity: var(--_opacity-disabled);
     cursor: not-allowed;
   }
 }

package/src/components/forms/form/form.api.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "Auto-generated from index.scss annotations. Do not edit manually — run: pnpm generate:api",
+  "name": "form",
+  "element": "form",
+  "modifiers": {
+    "compact": {
+      "type": "boolean"
+    },
+    "inline": {
+      "type": "boolean"
+    }
+  },
+  "elements": {
+    "section": {},
+    "actions": {}
+  },
+  "relatedComponents": [
+    {
+      "name": "form-error"
+    },
+    {
+      "name": "form-helper"
+    }
+  ],
+  "cssVars": [
+    {
+      "name": "--ui-form-spacing",
+      "default": "var(--ui-space-3)",
+      "description": "Spacing"
+    },
+    {
+      "name": "--ui-form-actions-gap",
+      "default": "var(--ui-space-2)",
+      "description": "Actions gap"
+    },
+    {
+      "name": "--ui-form-section-spacing",
+      "default": "var(--ui-space-4)",
+      "description": "Section spacing"
+    }
+  ]
+}

package/src/{04-components → components}/forms/form/index.scss

@@ -1,12 +1,18 @@
-@use '../../../00-config/tokens/variables' as t;
+@use '../../../config/tokens/variables' as t;
+// @component form
+// @element form
+// @related form-error, form-helper
 
 // Form - layout container for form fields
 // Provides consistent vertical spacing between fields, sections, and actions
 
 @layer components.tokens {
   .form {
+    // @desc Spacing
     --_spacing: var(--ui-form-spacing, var(--ui-space-3, calc(#{t.$unit} * 3)));
+    // @desc Actions gap
     --_actions-gap: var(--ui-form-actions-gap, var(--ui-space-2, calc(#{t.$unit} * 2)));
+    // @desc Section spacing
     --_section-spacing: var(--ui-form-section-spacing, var(--ui-space-4, calc(#{t.$unit} * 4)));
   }
 }
@@ -44,12 +50,16 @@
   }
 
   // Compact variant - tighter spacing
+  // @modifier boolean compact
   .form--compact {
+    // @desc Spacing compact
     --_spacing: var(--ui-form-spacing-compact, var(--ui-space-2, calc(#{t.$unit} * 2)));
+    // @desc Section spacing compact
     --_section-spacing: var(--ui-form-section-spacing-compact, var(--ui-space-3, calc(#{t.$unit} * 3)));
   }
 
   // Inline variant - horizontal layout for short forms (search, filters)
+  // @modifier boolean inline
   .form--inline {
     flex-direction: row;
     flex-wrap: wrap;

package/src/components/forms/form-error/form-error.api.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "Auto-generated from index.scss annotations. Do not edit manually — run: pnpm generate:api",
+  "name": "form-error",
+  "element": "div",
+  "modifiers": {},
+  "elements": {
+    "icon": {}
+  },
+  "cssVars": [
+    {
+      "name": "--ui-form-error-color",
+      "default": "var(--ui-color-danger)",
+      "description": "Text color"
+    },
+    {
+      "name": "--ui-form-error-size",
+      "default": "var(--ui-font-size-sm)",
+      "description": "Overall size"
+    },
+    {
+      "name": "--ui-form-error-gap",
+      "default": "0",
+      "description": "Gap between children"
+    }
+  ]
+}

package/src/{04-components → components}/forms/form-error/form-error.docs.json

@@ -9,7 +9,7 @@
       "title": "Default",
       "examples": [
         {
-          "html": "<span class=\"ui-form-error\">This field is required</span>",
+          "items": [{ "tag": "span", "class": "ui-form-error", "text": "This field is required" }],
           "code": "<span class=\"ui-form-error\">This field is required</span>"
         }
       ]
@@ -18,7 +18,28 @@
       "title": "With Icon",
       "examples": [
         {
-          "html": "<span class=\"ui-form-error\"><svg class=\"ui-form-error__icon ui-icon ui-icon--sm\" viewBox=\"0 0 24 24\" fill=\"currentColor\"><path d=\"M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z\"/></svg>Please enter a valid email</span>",
+          "items": [
+            {
+              "tag": "span",
+              "class": "ui-form-error",
+              "children": [
+                {
+                  "tag": "svg",
+                  "class": "ui-form-error__icon ui-icon ui-icon--sm",
+                  "attrs": { "viewBox": "0 0 24 24", "fill": "currentColor" },
+                  "children": [
+                    {
+                      "tag": "path",
+                      "attrs": {
+                        "d": "M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm1 15h-2v-2h2v2zm0-4h-2V7h2v6z"
+                      }
+                    }
+                  ]
+                },
+                { "tag": "span", "text": "Please enter a valid email" }
+              ]
+            }
+          ],
           "code": "<span class=\"ui-form-error\">\n  <svg class=\"ui-form-error__icon ui-icon ui-icon--sm\">...</svg>\n  Please enter a valid email\n</span>"
         }
       ]

package/src/{04-components → components}/forms/form-error/index.scss

@@ -1,12 +1,18 @@
-@use '../../../00-config/tokens/variables' as t;
+@use '../../../config/tokens/variables' as t;
+// @component form-error
+// @element div
 
 // Form Error - validation error message for form fields
 // Displays error text with danger color
 
 @layer components.tokens {
   .form-error {
+    --_leading-tight-sm: var(--ui-leading-tight-sm, var(--ui-row-1));
+    // @desc Text color
     --_color: var(--ui-form-error-color, var(--ui-color-danger));
+    // @desc Overall size
     --_size: var(--ui-form-error-size, var(--ui-font-size-sm, #{t.$font-size-sm}));
+    // @desc Gap between children
     --_gap: var(--ui-form-error-gap, 0);
   }
 }
@@ -20,7 +26,7 @@
     margin-block-start: var(--_gap);
 
     font-size: var(--_size);
-    line-height: var(--ui-leading-tight-sm, var(--ui-row-1));
+    line-height: var(--_leading-tight-sm);
     color: var(--_color);
   }
 

package/src/components/forms/form-helper/form-helper.api.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "Auto-generated from index.scss annotations. Do not edit manually — run: pnpm generate:api",
+  "name": "form-helper",
+  "element": "div",
+  "modifiers": {},
+  "cssVars": [
+    {
+      "name": "--ui-form-helper-color",
+      "default": "var(--ui-color-text-muted)",
+      "description": "Text color"
+    },
+    {
+      "name": "--ui-form-helper-size",
+      "default": "var(--ui-font-size-sm)",
+      "description": "Overall size"
+    },
+    {
+      "name": "--ui-form-helper-gap",
+      "default": "0",
+      "description": "Gap between children"
+    }
+  ]
+}

package/src/{04-components → components}/forms/form-helper/form-helper.docs.json

@@ -9,7 +9,9 @@
       "title": "Default",
       "examples": [
         {
-          "html": "<span class=\"ui-form-helper\">Must be at least 8 characters</span>",
+          "items": [
+            { "tag": "span", "class": "ui-form-helper", "text": "Must be at least 8 characters" }
+          ],
           "code": "<span class=\"ui-form-helper\">Must be at least 8 characters</span>"
         }
       ]