@guildofgleks/ui 0.0.1 → 21.2.2

package/LICENSE

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

@@ -1,64 +1,192 @@
-# Ui
-
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 21.2.0.
-
-## Code scaffolding
-
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
-
-```bash
-ng generate component component-name
-```
-
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
-
-```bash
-ng generate --help
-```
-
-## Building
-
-To build the library, run:
-
-```bash
-ng build ui
-```
-
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
-
-### Publishing the Library
-
-Once the project is built, you can publish your library by following these steps:
-
-1. Navigate to the `dist` directory:
-
-   ```bash
-   cd dist/ui
-   ```
-
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
-
-## Running unit tests
-
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
-
-```bash
-ng test
-```
-
-## Running end-to-end tests
-
-For end-to-end (e2e) testing, run:
-
-```bash
-ng e2e
-```
-
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
-
-## Additional Resources
-
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+![NPM Version](https://img.shields.io/npm/v/@guildofgleks/ui?color=red)
+![Node Version](https://img.shields.io/node/v/@guildofgleks/ui)
+![Angular 21](https://img.shields.io/badge/Angular-21%2B-dd0031?logo=angular)
+![NPM Downloads](https://img.shields.io/npm/dm/@guildofgleks/ui)
+![License](https://img.shields.io/npm/l/@guildofgleks/ui)
+
+A lightweight Angular 21 component library. No CDK, no Material — the only runtime
+dependencies are `@angular/core`, `@angular/common` and `@angular/forms`.
+
+**Tags:** angular, angular21, components, ui-library, design-system, signals, standalone, accessible
+
+## Features
+
+- 16 standalone components — accordion, button, checkbox, chip, dialog, icon,
+  inputfield, multiselect, paginator, select, skeleton, slider, spinner, table, tag,
+  toast — plus `DialogService`, `ToastService` and `ThemeService`.
+- Signal-based API throughout: `input()` / `output()` / `model()`, `OnPush` change
+  detection, no NgModules.
+- No CDK, no Material — a small dependency footprint on top of `@angular/core`,
+  `@angular/common` and `@angular/forms`.
+- Full theming through CSS custom properties: restyle any component, swap the whole
+  palette, or ship light/dark and custom themes at runtime via a `data-theme` attribute.
+- `ControlValueAccessor` on every form control (checkbox, inputfield, select,
+  multiselect, slider) — works with `formControl`, `formControlName` and `ngModel`.
+- Accessible by default: keyboard navigation, ARIA attributes, WCAG AA contrast.
+
+## Install
+
+npm:
+
+```bash
+npm install @guildofgleks/ui
+```
+
+yarn:
+
+```bash
+yarn add @guildofgleks/ui
+```
+
+## Setup
+
+Add the stylesheet once. It carries the baseline theme (every token the components
+read) plus the utility classes the component templates use, so without it components
+render unstyled.
+
+```jsonc
+// angular.json → projects.<app>.architect.build.options
+"styles": [
+  "node_modules/@guildofgleks/ui/styles/index.css",
+  "src/styles.scss" // your own styles, after the baseline so they win
+]
+```
+
+Then import a component where you need it:
+
+```ts
+import { Component } from '@angular/core';
+import { ButtonComponent, SelectComponent } from '@guildofgleks/ui';
+
+@Component({
+  selector: 'app-example',
+  imports: [ButtonComponent, SelectComponent],
+  template: `
+    <gog-select label="Region" [options]="regions" [(value)]="region" />
+    <gog-button (gogClick)="save()">Save</gog-button>
+  `,
+})
+export class ExampleComponent {
+  /* … */
+}
+```
+
+Outputs are prefixed with `gog` (`gogClick`, `gogToggle`) so they never collide with
+native DOM events. Inputs keep their natural names.
+
+## Theming
+
+Everything is themed through CSS custom properties, and **every value the components
+paint with lives in `styles/theme.css`** — no component stylesheet holds a colour, font,
+border, radius, shadow, spacing or duration of its own. There are three layers:
+
+**1. Foundation tokens** — the palette, type scale, spacing, motion and control metrics.
+Override these to restyle everything at once; the component tokens all derive from them,
+so a palette swap carries through without touching anything else.
+
+| Group | Tokens |
+| --- | --- |
+| Palette | `--gog-background-color`, `--gog-surface-color`, `--gog-text-color`, `--gog-accent-text-color`, `--gog-muted-text-color`, `--gog-primary-color`, `--gog-secondary-color`, `--gog-accent-color`, `--gog-accent-bright`, `--gog-accent-dim`, `--gog-accent-pale`, `--gog-border-color`, `--gog-hover-color` |
+| Status | `--gog-success-color`, `--gog-danger-color`, `--gog-warning-color`, `--gog-info-color` |
+| Type | `--gog-font-heading`, `--gog-font-body`, `--gog-font-mono`, `--gog-text-xs` … `--gog-text-3xl` |
+| Geometry | `--gog-radius`, `--gog-space-xs` … `--gog-space-2xl`, `--gog-panel-shadow`, `--gog-panel-radius`, `--gog-panel-border-width`, `--gog-panel-border-style` |
+| Motion | `--gog-duration-fast`, `--gog-duration-base`, `--gog-duration-slow`, `--gog-easing` |
+| Focus / state | `--gog-focus-ring-width`, `--gog-focus-ring-offset`, `--gog-disabled-opacity` |
+| Controls | `--gog-control-padding-y`, `--gog-control-padding-x`, `--gog-control-icon-offset`, `--gog-control-border-width`, `--gog-control-border-style` |
+| Fields | `--gog-field-{xsm,sm,md,lg,slg}-{padding-y,padding-x,font-size,icon-offset,icon-inset}` — shared by input, select and multiselect |
+| Buttons | `--gog-btn-{xsm,sm,md,lg,slg}-padding`, `--gog-btn-{xsm,sm,md,lg,slg}-font-size` |
+| Checkables | `--gog-control-checkbox-padding`, `--gog-control-checkbox-box-size-{xsm…slg}`, `--gog-control-checkbox-label-size-{xsm…slg}`, `--gog-control-checkbox-icon-size-{xsm…slg}` |
+| Overlays | `--gog-dropdown-z`, `--gog-spinner-overlay-z` |
+
+**2. Component tokens** — `--gog-<block>-*`, one block per component in `theme.css`, for
+restyling a single component theme-wide. They cover every painted property, including
+per-variant and per-size values (`--gog-btn-ghost-hover-bg`, `--gog-tag-lg-padding-block`,
+`--gog-accordion-sm-chevron-size`, `--gog-skeleton-shine`, `--gog-paginator-gap`, …), plus
+each component's font family, so a theme can decide that e.g. buttons use the body face:
+
+```css
+:root[data-theme='mine'] {
+  --gog-btn-font-family: var(--gog-font-body);
+  --gog-btn-font-weight: 600;
+  --gog-btn-ghost-hover-bg: color-mix(in srgb, var(--gog-accent-color) 20%, transparent);
+  --gog-table-hover-bg: var(--gog-hover-color);
+}
+```
+
+**3. Instance tokens** — a small set left deliberately *undeclared* so that setting them
+anywhere always wins over the variant/size classes. This is the per-instance escape
+hatch:
+
+```css
+.my-form gog-button {
+  --gog-btn-bg: rebeccapurple;   /* beats .gog-btn--primary, unlike a declared token */
+}
+```
+
+They are `--gog-btn-{bg,color,border,shadow,hover-bg,hover-color,hover-shadow,padding,font-size,spinner-color}`,
+`--gog-tag-{accent,bg,border,color,font-size,gap,padding-block,padding-inline,icon-size}`,
+`--gog-chip-{font-size,gap,padding-block,padding-inline,avatar-size,icon-size,remove-size}`,
+the per-size field hooks (`--gog-input-padding-y`, `--gog-select-control-font`,
+`--gog-ms-font-size`, `--gog-table-td-padding-v`, `--gog-accordion-padding-y`, …) and
+`--gog-spinner-color`.
+
+### Light and dark
+
+The theme is selected with a `data-theme` attribute on `:root`, and `ThemeService`
+manages it:
+
+```ts
+private readonly theme = inject(ThemeService);
+this.theme.toggleTheme();         // light ⇄ dark
+this.theme.setTheme('cyberpunk'); // any custom theme name
+```
+
+To add a theme, copy a palette block from `styles/theme.css` and change the attribute
+value. A theme only needs to declare what it actually changes — the component tokens are
+re-derived from whatever palette is in scope, so a swapped `--gog-accent-color` reaches every
+component without listing any of them:
+
+```css
+:root[data-theme='cyberpunk'],
+[data-theme='cyberpunk'] {
+  color-scheme: dark;
+  --gog-background-color: #050816;
+  --gog-accent-color: #ff4edb;
+  --gog-radius: 22px;
+}
+```
+
+The second selector is what lets a theme apply to a *subtree* rather than the whole page
+— put `data-theme="cyberpunk"` on any element and everything inside it re-derives from
+that palette, so one page can show several themes side by side (see the showcase's Theme
+lab). That works because `theme.css` re-declares its derived layer on `:root, [data-theme]`:
+a custom property's `var()` references are substituted where the property is *declared*,
+so a derived token declared only on `:root` would freeze to the root palette.
+
+Corollary worth knowing when writing your own themes: **anything you declare that reads
+another token must sit on the theme scope itself**, not on `:root`, or it will not follow
+a nested theme.
+
+### Optional font preset
+
+`styles/index.css` intentionally leaves fonts alone — generic system stacks, no webfont
+download. For the showcase's typography (Cinzel / Inter / JetBrains Mono, pulled from
+Google Fonts) add `@guildofgleks/ui/styles/fonts.css` as well.
+
+## Components
+
+`gog-accordion`, `gog-button`, `gog-checkbox`, `gog-chip`, `gog-dialog`, `gog-icon`,
+`gog-inputfield`, `gog-multiselect`, `gog-paginator`, `gog-select`, `gog-skeleton`,
+`gog-slider`, `gog-spinner`, `gog-spinner-overlay`, `gog-table`, `gog-tag`, `gog-toast`.
+
+Services: `DialogService`, `ToastService`, `ThemeService`.
+
+`gog-checkbox`, `gog-inputfield`, `gog-select`, `gog-multiselect` and `gog-slider`
+implement `ControlValueAccessor`, so they work with `[formControl]`, `formControlName`
+and `ngModel`. With a form control attached, the error message appears once the control
+is both touched and invalid; without one it shows for as long as `errorMessage` is
+non-empty, and the consumer decides when to clear it.
+
+## License
+
+MIT © Roman Malitskyi