@ahrowe/ui 0.4.2 → 0.4.3

package/docs/ConfigProvider.md

@@ -0,0 +1,81 @@
+# ConfigProvider
+
+**When to use:** Set global **default props** for library components once, near the root of your app, instead of repeating the same prop on every instance. If your app always wants floating labels, set `Input.alwaysFloatLabel` here and every `Input` picks it up.
+
+**Import:** `import { ConfigProvider } from '@ahrowe/ui'`
+**Types:** `import type { ComponentDefaults, ConfigProviderProps } from '@ahrowe/ui'`
+
+Place it inside `ThemeProvider` (it's a separate concern from theming — theme = CSS variables, config = default props):
+
+```tsx
+import { ThemeProvider, ConfigProvider } from '@ahrowe/ui';
+
+<ThemeProvider>
+  <ConfigProvider defaultProps={{ Input: { alwaysFloatLabel: true } }}>
+    <App />
+  </ConfigProvider>
+</ThemeProvider>
+```
+
+## How defaults resolve
+
+For each prop, the value is chosen in this order (first that's set wins):
+
+1. The prop **explicitly passed** to the component instance
+2. The matching **global default** from the nearest `ConfigProvider`
+3. The component's own **built-in default**
+
+So a global default only fills in props a given instance left out — any instance can still override it:
+
+```tsx
+<ConfigProvider defaultProps={{ Input: { alwaysFloatLabel: true } }}>
+  <Input label="Name" />                        {/* floats — inherits the global default */}
+  <Input label="Note" alwaysFloatLabel={false} />{/* opts out — explicit prop wins        */}
+</ConfigProvider>
+```
+
+## Nesting
+
+`ConfigProvider`s compose. A nested provider extends the outer one per component, overriding only the keys it sets:
+
+```tsx
+<ConfigProvider defaultProps={{ Input: { alwaysFloatLabel: true, useMatLabelStyle: true } }}>
+  {/* Inputs here float and use the material label */}
+  <ConfigProvider defaultProps={{ Input: { alwaysFloatLabel: false } }}>
+    {/* Inputs here don't float, but still use the material label from the outer provider */}
+  </ConfigProvider>
+</ConfigProvider>
+```
+
+## Key props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `defaultProps` | `ComponentDefaults` | Default props keyed by component name, e.g. `{ Input: { alwaysFloatLabel: true } }` |
+| `children` | `ReactNode` | Your app content |
+
+## Supported components
+
+Each entry is a `Partial<...Props>`, so any of that component's props can be defaulted:
+
+- **Form inputs:** `Input` · `Textarea` · `NumberInput` · `Dropdown` · `InputDropdown` · `Checkbox` · `Switch` · `DatePicker`
+- **Display:** `Button` · `ActionButtons` · `Badge` · `Chip` · `Card` · `Skeleton` · `Accordion`
+
+```tsx
+<ConfigProvider
+  defaultProps={{
+    Input: { alwaysFloatLabel: true },
+    Dropdown: { useMatLabelStyle: true },
+    NumberInput: { decimalScale: 2, thousandSeparator: '.' },
+    Button: { styleType: ButtonStyleType.Primary },
+    Card: { styleType: CardStyleType.Outlined },
+    Skeleton: { animation: SkeletonAnimation.Pulse },
+  }}
+>
+  <App />
+</ConfigProvider>
+```
+
+`Textarea`, `NumberInput`, and `DatePicker` are built on top of `Input`, so they **also** inherit `Input` defaults for the props they forward to it. Their own component-keyed defaults take precedence for props they handle themselves. Example: with `Input: { alwaysFloatLabel: true }` set, every `Textarea` / `NumberInput` / `DatePicker` floats its label too, without needing a separate entry.
+
+The `ComponentDefaults` type is the source of truth for which keys are currently supported — more components adopt it over time.

package/docs/Dropdown.md

@@ -53,5 +53,6 @@ const statusValidator = new FormValidator('', [Validators.required()]);
 | `placeholder` | `string` | Placeholder when no selection |
 | `onScroll` | `() => Promise<void>` | Load more on list scroll |
 | `useMatLabelStyle` | `boolean` | Material-style floating label |
+| `alwaysFloatLabel` | `boolean` | Keep the material label floated in the border notch even when nothing is selected, so an empty dropdown reads as blank instead of showing the label as if it were the selected value. Only applies with `useMatLabelStyle` (default) |
 
 The list is rendered through a portal and tracks the trigger across scroll, so it always escapes clipping ancestors (cards, scroll containers, virtualized lists). It flips to open upward automatically when there's no room below, and hides (without closing) if the trigger itself scrolls behind a clipping ancestor, reappearing once it's back in view.

package/docs/Input.md

@@ -66,6 +66,7 @@ const emailValidator = new FormValidator('', [Validators.required(), Validators.
 | `onClearClicked` | `() => void` | Clear button handler |
 | `isRow` | `boolean` | Horizontal layout |
 | `labelInBorder` | `boolean` | Label inside fieldset border |
+| `alwaysFloatLabel` | `boolean` | Keep the material label floated in the border notch even when empty and unfocused, so an empty field reads as blank instead of showing the label as if it were a value. Only applies with `useMatLabelStyle` (default) |
 | `readOnly` | `boolean` | |
 | `autoFocus` | `boolean` | |
 | `placeholder` | `string` | |

package/docs/ThemeProvider.md

@@ -70,6 +70,8 @@ interface Theme {
 | `--error-color` / `--success-color` / `--warn-color` / `--info-color` | Semantic colours |
 | `--default-border-radius` | Border radii |
 | `--avatar-radius` | `Avatar` corner radius — falls back to `--default-border-radius` when unset (set to `50%` theme-wide for fully circular avatars) |
+| `--input-label-resting-color` | Resting (not-floated) material label colour for `Input` & `Dropdown` — falls back to `--text-light` when unset |
+| `--input-label-floating-color` | Floating (active) material label colour for `Input` & `Dropdown` — falls back to `--text-color` when unset |
 | `--card-shadow` | Elevation shadows |
 
 **Key props:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ahrowe/ui",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "publishConfig": {
     "access": "public"
   },