@alisonquinter17/alieta-ui 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alison Quintero
+
+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,54 +1,298 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Alieta UI
 
-## Getting Started
+A small React component library: `Button`, `Icon`, `Loader` and `Spinner`.
 
-First, run the development server:
+Alieta ships a **compiled stylesheet**, so you do not need Tailwind, a
+`safelist`, or any build configuration to use it. Everything visual is driven by
+CSS variables you can override.
+
+> **Pre-1.0 — the API can still change.** While the version is `0.x`, a minor
+> bump (`0.1.x` → `0.2.0`) may contain breaking changes. Pin an exact version if
+> that matters to you.
+
+## Requirements
+
+- React **18.2** or **19** (and the matching `react-dom`)
+- Any React setup: Next.js, Vite, Remix, CRA — Alieta is framework-agnostic and
+  has **zero runtime dependencies**
+
+## Installation
 
 ```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
+npm install @alisonquinter17/alieta-ui
+```
+
+Then import the stylesheet **once**, at the root of your app:
+
+```ts
+import "@alisonquinter17/alieta-ui/styles.css";
 ```
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+That is the entire setup. The stylesheet contains no reset and no Tailwind
+Preflight, so it will not restyle your headings, lists or form controls. Every
+class it defines is namespaced `alieta:*` and every variable `--alieta-*`, so it
+cannot collide with your own CSS.
+
+## Components
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+### Button
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+```tsx
+import { Button } from "@alisonquinter17/alieta-ui";
+
+<Button onClick={save}>Save</Button>
+<Button variant="secondary" size="large">Cancel</Button>
+<Button variant="destructive" onClick={remove}>Delete</Button>
+<Button isLoading>Saving...</Button>
+```
 
-## Learn More
+A real `<button>`: it forwards its ref, accepts every native button prop, and
+defaults to `type="button"` so it never submits a form by accident.
 
-To learn more about Next.js, take a look at the following resources:
+| Prop        | Type                                                       | Default     | Notes                                                        |
+| ----------- | ---------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
+| `variant`   | `"primary" \| "secondary" \| "ghost" \| "destructive"`      | `"primary"` |                                                              |
+| `size`      | `"small" \| "medium" \| "large"`                            | `"medium"`  |                                                              |
+| `icon`      | `ReactNode`                                                 | —           | Rendered before the label, exactly as given                  |
+| `isLoading` | `boolean`                                                   | `false`     | Disables the button and sets `aria-busy="true"`              |
+| `disabled`  | `boolean`                                                   | `false`     | `isLoading` also disables; `disabled={false}` cannot undo it |
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+Plus every prop of `React.ButtonHTMLAttributes<HTMLButtonElement>`.
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+`icon` takes any node — Alieta's `<Icon>`, your own SVG, or a component from an
+icon package:
+
+```tsx
+<Button icon={<Icon name="blumio" iconSize="sm" />}>Bundled icon</Button>
+<Button icon={<MyCheckIcon />}>Your own SVG</Button>
+```
+
+An icon-only button needs its own accessible name:
+
+```tsx
+<Button aria-label="Delete" icon={<TrashIcon />} />
+```
+
+### Icon
+
+```tsx
+import { Icon } from "@alisonquinter17/alieta-ui";
+
+<Icon name="blumio" iconSize="xl" />            {/* decorative */}
+<Icon name="blumio" iconSize="xl" label="Blumio" /> {/* meaningful */}
+```
 
-## Deploy on Vercel
+Icons are bundled React components — no CDN script, no `<ion-icon>` custom
+element to register, no icon font. `name` is typed, so only icons that actually
+ship can be requested.
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
+| Prop       | Type                                                | Default | Notes                                        |
+| ---------- | --------------------------------------------------- | ------- | -------------------------------------------- |
+| `name`     | `"blumio"`                                          | —       | Typed; unknown names are rejected at compile time |
+| `iconSize` | `"xs"` … `"6xl"`                                    | `"md"`  | 12px, 16px, 24px, 36px, 48px, 64px, 96px, 128px, 160px, 192px |
+| `label`    | `string`                                            | —       | Omit for decorative icons (they get `aria-hidden`); set it when the icon carries the meaning |
 
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+The library intentionally ships a **small** registry — right now just the Blumio
+mark. For anything else, pass your own SVG straight to the component that needs
+it. The mark uses `currentColor`, so it takes the colour of its container.
 
-## 🎨 TailwindCSS Configuration
+`Icon` is **presentational, not a control.** It renders a `<span>`, which is not
+focusable and not reachable by keyboard, so it should never be used as a button.
+The type enforces this: every event handler (`onClick`, `onKeyDown`,
+`onPointerDown`, …), `role`, `tabIndex`, `accessKey`, `autoFocus`,
+`contentEditable` and `draggable` are rejected at compile time. `children` and
+`dangerouslySetInnerHTML` are rejected too, and so are `aria-label` and
+`aria-hidden`, which `Icon` derives from `label`. `className`, `style`, `id`,
+`title`, `data-*` and descriptive `aria-*` attributes are still accepted.
 
-To ensure styles are properly applied, add the following to your `tailwind.config.js`:
+Any interaction belongs on a real control. For a clickable icon, put it inside a
+`Button`:
 
-```javascript
-module.exports = {
-  content: [
-    // Your existing content paths...
-    "./src/**/*.{js,ts,jsx,tsx}",
-    // Add this line to include Alieta UI source files
-    "./node_modules/@alisonquinter17/alieta-ui/src/**/*.{js,ts,jsx,tsx}",
-  ],
-  // ... rest of your config
+```tsx
+<Button aria-label="Delete" icon={<Icon name="blumio" iconSize="sm" />} />
+```
+
+The same goes for interactive tooltips: the trigger must be a focusable element
+such as a `Button`, not the icon itself, or keyboard users cannot open it.
+
+A dedicated `IconButton` component is planned for a later release.
+
+### Loader and Spinner
+
+```tsx
+import { Loader, Spinner } from "@alisonquinter17/alieta-ui";
+
+<Loader />                                   {/* full-viewport overlay */}
+<Loader message="Loading data..." />
+<Loader showOverlay={false} />               {/* fills its container */}
+<Spinner label="Saving" />                   {/* inline indicator */}
+```
+
+`Loader` is a single `role="status"` live region containing a decorative
+spinner, so the busy state is announced exactly **once**.
+
+| Prop (`Loader`) | Type        | Default     | Notes                                                    |
+| --------------- | ----------- | ----------- | -------------------------------------------------------- |
+| `message`       | `ReactNode` | —           | A plain string also becomes the accessible name           |
+| `showOverlay`   | `boolean`   | `true`      | Renders as a `position: fixed` full-viewport layer        |
+| `label`         | `string`    | `"Loading"` | Accessible name when `message` is absent or not plain text |
+
+**About the overlay:** it is a plain positioned element. It adds no global
+styles and does **not** lock page scrolling — your app stays in control of that.
+
+| Prop (`Spinner`) | Type                                 | Default     | Notes                                            |
+| ---------------- | ------------------------------------ | ----------- | ------------------------------------------------ |
+| `size`           | `"small" \| "medium" \| "large"`     | `"medium"`  | 16px, 20px, 32px                                 |
+| `label`          | `string \| null`                     | `"Loading"` | `null` hides it from screen readers — use it next to something that already announces the busy state |
+
+Both accept `className` and their native element props.
+
+## Theming
+
+Every colour and shape comes from a CSS variable with a sensible default.
+Override the ones you care about in your own `:root` — unprefixed declarations
+beat Tailwind's `@layer`, so you never need `!important`:
+
+```css
+:root {
+  --alieta-color-primary: #2f6f62;
+  --alieta-color-primary-hover: #255a4f;
+  --alieta-radius: 0.75rem;
 }
 ```
 
-**Important**: Make sure your project has TailwindCSS installed and configured. Alieta UI components use TailwindCSS utility classes and require the consumer project to process these classes.
+You can scope an override to any subtree instead of the whole page:
+
+```tsx
+<section style={{ "--alieta-color-primary": "#2f6f62" } as React.CSSProperties}>
+  <Button>Themed just in here</Button>
+</section>
+```
+
+### Tokens
+
+| Token                             | Default   | Used by                                  |
+| --------------------------------- | --------- | ---------------------------------------- |
+| `--alieta-color-primary`          | `#6d28d9` | Primary button background                |
+| `--alieta-color-primary-hover`    | `#5b21b6` | Primary button hover                     |
+| `--alieta-color-primary-contrast` | `#ffffff` | Text on the primary background           |
+| `--alieta-color-secondary`        | `#6d28d9` | Secondary / ghost border and text        |
+| `--alieta-color-secondary-hover`  | `#5b21b6` | Secondary / ghost hover                  |
+| `--alieta-color-danger`           | `#be123c` | Destructive button                       |
+| `--alieta-color-danger-hover`     | `#9f1239` | Destructive button hover                 |
+| `--alieta-color-surface`          | `#ffffff` | Loader overlay background                |
+| `--alieta-color-border`           | `#d4d4d8` | Border of disabled outlined buttons      |
+| `--alieta-color-muted`            | `#52525b` | Loader message text                      |
+| `--alieta-color-disabled-surface` | `#e4e4e7` | Disabled button background               |
+| `--alieta-color-disabled-content` | `#71717a` | Disabled button text                     |
+| `--alieta-radius`                 | `0.5rem`  | Button corner radius                     |
+| `--alieta-focus-ring`             | `2px solid var(--alieta-color-primary)` | `:focus-visible` outline |
+| `--alieta-focus-ring-offset`      | `2px`     | Gap between the ring and the element      |
+| `--alieta-text-body-s/m/l`        | `0.875` / `0.9375` / `1rem` | Small / medium / large button text |
+
+The defaults meet WCAG AA: white on `--alieta-color-primary` is 7.1:1, and
+`--alieta-color-danger` on white is 6.3:1. If you change these colours, check
+the contrast of your own pair.
+
+## Usage in Next.js
+
+Alieta is a plain React library — it does **not** depend on Next.js and will not
+pull a copy of it into your project. Import the stylesheet in your root layout:
+
+```tsx
+// app/layout.tsx
+import "@alisonquinter17/alieta-ui/styles.css";
+import "./globals.css"; // your own CSS last, so your token overrides win
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+The components are plain client-side React. They have no `"use client"`
+directive, so import them from a Client Component (or add the directive in your
+own wrapper) when you need interactivity.
+
+## Usage in Vite
+
+```tsx
+// src/main.tsx
+import "@alisonquinter17/alieta-ui/styles.css";
+```
+
+Nothing else to configure.
+
+## Local development
+
+```bash
+npm ci                  # install
+npm run dev             # Storybook on http://localhost:6006
+npm run lint            # ESLint
+npm run typecheck       # tsc --noEmit
+npm test                # Vitest, once
+npm run test:watch      # Vitest, watch mode
+npm run build           # build dist/ (JS, styles.css, .d.ts)
+npm run build:storybook # static Storybook
+npm run check           # lint + typecheck + test + build
+```
+
+### Storybook
+
+`npm run dev` (or `npm run storybook`) opens Storybook on port 6006. It loads
+the same `styles.css` that ships in the package, so what you see there is what
+consumers get. The a11y addon reports accessibility violations in its panel.
+
+### Tests
+
+Vitest with jsdom and Testing Library. No browser download is needed, so
+`npm test` works the same locally and in CI.
+
+### Build
+
+Vite in library mode produces:
+
+- `dist/index.js` — ESM. React and the JSX runtime stay external.
+- `dist/styles.css` — the compiled stylesheet (Tailwind v4 with `prefix(alieta)`, no Preflight).
+- `dist/**/*.d.ts` — type declarations, excluding stories and tests.
+
+Tailwind is a **build-time** tool here. It never reaches the consumer.
+
+## Publishing
+
+`npm publish` is not run by hand. Publishing happens through GitHub Actions
+using npm **Trusted Publishing** (OIDC) — there is no `NPM_TOKEN` and no secret
+anywhere in the repository.
+
+1. Update the version with `npm version <patch|minor|major>` and push the commit
+   and tag.
+2. Create a **GitHub Release** for that tag.
+3. Publishing the release runs `.github/workflows/publish.yml`, which installs,
+   lints, typechecks, tests, builds, and only then publishes. If any step fails,
+   nothing is published.
+
+### One-time npm setup
+
+On npmjs.com, under the package's **Settings → Trusted Publisher**, register
+exactly:
+
+| Field             | Value             |
+| ----------------- | ----------------- |
+| GitHub owner      | `AlisonQuinter17` |
+| Repository        | `Alieta-UI`       |
+| Workflow filename | `publish.yml`     |
+| Allowed action    | `npm publish`     |
+
+Leave the environment field empty (the workflow does not use one).
+
+## Versioning
+
+[Semantic Versioning](https://semver.org). While the package is `0.x`, minor
+releases may break the API — see the pre-1.0 note at the top.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/components/Buttons/Button.d.ts

@@ -1,15 +1,15 @@
-import { HTMLProps, PropsWithChildren, ReactNode } from 'react';
-import { IconSize } from '../Icons/Icon';
+import { ButtonHTMLAttributes, ReactNode } from 'react';
 export type ButtonVariant = "primary" | "secondary" | "ghost" | "destructive";
 export type ButtonSize = "small" | "medium" | "large";
-export interface ButtonProps extends Omit<HTMLProps<HTMLButtonElement>, "size"> {
-    variant: ButtonVariant;
-    icon?: ReactNode;
-    iconStyle?: React.CSSProperties;
-    iconSize?: IconSize;
-    padding?: string;
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Visual style of the button. */
+    variant?: ButtonVariant;
+    /** Controls height, padding and font size. */
     size?: ButtonSize;
+    /** Element rendered before the label. Decorative — give the button a text
+     *  label, or an `aria-label` when it is icon-only. */
+    icon?: ReactNode;
+    /** Swaps the icon for a spinner and disables the button. */
     isLoading?: boolean;
-    type?: "button" | "submit" | "reset";
 }
-export declare const Button: React.FC<PropsWithChildren<ButtonProps>>;
+export declare const Button: import('react').ForwardRefExoticComponent<ButtonProps & import('react').RefAttributes<HTMLButtonElement>>;

package/dist/components/Icons/Icon.d.ts

@@ -1,51 +1,75 @@
+import { DOMAttributes, HTMLAttributes } from 'react';
+import { BlumioSVG } from './blumio-icons/BlumioSVG';
+/**
+ * Every icon Alieta ships. Icons are bundled as React components — there is no
+ * CDN script, no custom element to register and no icon font to load.
+ *
+ * To render an icon that is not in here, pass your own SVG straight to the
+ * component that needs it (for example `<Button icon={<MySvg />} />`).
+ */
+declare const icons: {
+    blumio: typeof BlumioSVG;
+};
+export type IconName = keyof typeof icons;
+/** Sizes are the CSS lengths applied to the icon box. */
 declare const iconSizes: {
-    readonly xs: {
-        readonly width: "0.75rem";
-        readonly height: "0.75rem";
-    };
-    readonly sm: {
-        readonly width: "1rem";
-        readonly height: "1rem";
-    };
-    readonly md: {
-        readonly width: "1.5rem";
-        readonly height: "1.5rem";
-    };
-    readonly lg: {
-        readonly width: "2.25rem";
-        readonly height: "2.25rem";
-    };
-    readonly xl: {
-        readonly width: "3rem";
-        readonly height: "3rem";
-    };
-    readonly "2xl": {
-        readonly width: "4rem";
-        readonly height: "4rem";
-    };
-    readonly "3xl": {
-        readonly width: "6rem";
-        readonly height: "6rem";
-    };
-    readonly "4xl": {
-        readonly width: "8rem";
-        readonly height: "8rem";
-    };
-    readonly "5xl": {
-        readonly width: "10rem";
-        readonly height: "10rem";
-    };
-    readonly "6xl": {
-        readonly width: "12rem";
-        readonly height: "12rem";
-    };
+    readonly xs: "alieta:size-3";
+    readonly sm: "alieta:size-4";
+    readonly md: "alieta:size-6";
+    readonly lg: "alieta:size-9";
+    readonly xl: "alieta:size-12";
+    readonly "2xl": "alieta:size-16";
+    readonly "3xl": "alieta:size-24";
+    readonly "4xl": "alieta:size-32";
+    readonly "5xl": "alieta:size-40";
+    readonly "6xl": "alieta:size-48";
 };
 export type IconSize = keyof typeof iconSizes;
-export interface IconProps {
-    name: string;
+/**
+ * The props `Icon` deliberately refuses.
+ *
+ * A `<span>` is not focusable and not reachable by keyboard, so wiring it up as
+ * a control produces something a mouse user can operate and nobody else can.
+ * Rather than document that as a caveat, the type makes it impossible:
+ *
+ *  - Every event handler (`onClick`, `onKeyDown`, `onPointerDown`, …) —
+ *    interaction belongs on a real control. Use `Button` today, or the planned
+ *    `IconButton`.
+ *  - `role`, `tabIndex`, `accessKey`, `autoFocus`, `contentEditable`,
+ *    `draggable` — the escape hatches people reach for to fake a control out
+ *    of a `<span>`.
+ *  - `aria-label` / `aria-hidden` — `Icon` derives both from the `label` prop,
+ *    so they cannot drift out of sync with its `role`.
+ *  - `children` / `dangerouslySetInnerHTML` — the content is always the
+ *    bundled SVG named by `name`.
+ */
+type EventHandlerProps = Exclude<keyof DOMAttributes<HTMLSpanElement>, "children" | "dangerouslySetInnerHTML">;
+type RefusedProps = EventHandlerProps | "children" | "dangerouslySetInnerHTML" | "role" | "tabIndex" | "accessKey" | "autoFocus" | "contentEditable" | "draggable" | "aria-label" | "aria-hidden";
+/**
+ * Renders a bundled icon inside a `<span>`. Strictly presentational.
+ *
+ * Any interaction must use a real control — `Button` today, or the planned
+ * `IconButton`:
+ *
+ *   <Button aria-label="Delete" icon={<Icon name="blumio" iconSize="sm" />} />
+ *
+ * The same applies to interactive tooltips: the trigger must be a focusable
+ * element (a `Button`), not the icon itself, or keyboard users cannot reach it.
+ *
+ * `className`, `style`, `id`, `title`, `data-*` and descriptive `aria-*`
+ * attributes (`aria-describedby`, …) are still accepted.
+ */
+export interface IconProps extends Omit<HTMLAttributes<HTMLSpanElement>, RefusedProps> {
+    /** Which bundled icon to render. */
+    name: IconName;
+    /** @default "md" */
     iconSize?: IconSize;
-    iconStyle?: React.CSSProperties;
-    className?: string;
+    /**
+     * Accessible name. Leave it out for decorative icons — the icon is then
+     * hidden from assistive technology, which is the right default next to a
+     * text label. Set it when the icon is the only thing conveying meaning.
+     */
+    label?: string;
 }
-declare const Icon: React.FC<React.HTMLProps<HTMLSpanElement> & IconProps>;
-export default Icon;
+export declare function Icon({ name, iconSize, label, className, ...rest }: IconProps): import("react").JSX.Element | null;
+export {};

package/dist/components/Icons/blumio-icons/BlumioSVG.d.ts

@@ -1 +1,3 @@
-export declare const BlumioSVG: React.ComponentType<React.SVGProps<SVGSVGElement>>;
+import { SVGProps } from 'react';
+/** Blumio brand mark. Paths inherit `currentColor`, so it can be themed. */
+export declare function BlumioSVG(props: SVGProps<SVGSVGElement>): import("react").JSX.Element;

package/dist/components/Loader/Loader.d.ts

@@ -1,10 +1,32 @@
-import { ReactNode } from 'react';
-interface LoaderProps {
+import { HTMLAttributes, ReactNode } from 'react';
+export type SpinnerSize = "small" | "medium" | "large";
+export interface SpinnerProps extends HTMLAttributes<HTMLSpanElement> {
+    /** @default "medium" */
+    size?: SpinnerSize;
+    /**
+     * Accessible name announced by screen readers.
+     * Pass `null` when the spinner sits next to something that already announces
+     * the busy state (a button with `aria-busy`, a `<Loader>`), so the state is not
+     * read out twice.
+     * @default "Loading"
+     */
+    label?: string | null;
+}
+export declare function Spinner({ size, label, className, ...rest }: SpinnerProps): import("react").JSX.Element;
+export interface LoaderProps extends HTMLAttributes<HTMLDivElement> {
+    /** Optional text rendered under the spinner. */
     message?: ReactNode;
+    /**
+     * Renders the loader as a fixed, full-viewport overlay above the page.
+     * The overlay is a plain positioned element: it adds no global styles and
+     * does not lock scrolling — the host application stays in control.
+     * @default true
+     */
     showOverlay?: boolean;
+    /**
+     * Accessible name, used when `message` is absent or is not plain text.
+     * @default "Loading"
+     */
+    label?: string;
 }
-export declare const Loader: React.FC<LoaderProps>;
-export declare const Spinner: ({ className }: {
-    className?: string;
-}) => import("react/jsx-runtime").JSX.Element;
-export {};
+export declare function Loader({ message, showOverlay, label, className, ...rest }: LoaderProps): import("react").JSX.Element;

package/dist/index.d.ts

@@ -1 +1,6 @@
-export * from './components';
+export { Button } from './components/Buttons/Button';
+export type { ButtonProps, ButtonSize, ButtonVariant } from './components/Buttons/Button';
+export { Icon } from './components/Icons/Icon';
+export type { IconName, IconProps, IconSize } from './components/Icons/Icon';
+export { Loader, Spinner } from './components/Loader/Loader';
+export type { LoaderProps, SpinnerProps, SpinnerSize } from './components/Loader/Loader';