@tartaguti/ui-components 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @tartaguti/ui-components
+
+## 0.2.0
+
+### Minor Changes
+
+- 4e3b89f: tt-data-table can be virtualized: `visible-rows` makes it a box that many rows tall holding only the rows in view, so 10,000 rows scroll as smoothly as 10. Screen readers still hear the true row position, columns no longer jump while scrolling, and `tt-range-change` reports which rows are in view. Cells use tighter sides on phones.
+
+## 0.1.0
+
+First public release: 85 Lit web components, design tokens with dark
+mode, density and theme presets, tested in Chromium and Firefox (WebKit
+in CI).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 negilatifi
+
+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,3 +1,193 @@
-# Temporary Holding Version
+# @tartaguti/ui-components
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/negilatifi/tartaguti-base/actions/workflows/ci.yml/badge.svg)](https://github.com/negilatifi/tartaguti-base/actions/workflows/ci.yml)
+
+Reusable Lit web components. Framework-agnostic: they are custom elements,
+so they work in plain HTML, Vite, Next.js, Astro, Rails, or anything else
+that can render a tag.
+
+## Install
+
+```bash
+npm install @tartaguti/ui-components lit
+```
+
+`lit` is a **peer dependency**, which means you install it, not the
+library. That is deliberate: two copies of Lit on one page means two
+custom-element registries and duplicate-definition errors. One copy,
+owned by the app.
+
+## Setup, once per app
+
+```ts
+// Design tokens. The library does not work without these: every
+// component reads var(--tt-*) and gets nothing if they are absent.
+import "@tartaguti/ui-components/tokens.css";
+```
+
+Then import what you use:
+
+```ts
+// Everything. Simple, and fine for an app that uses most of it.
+import "@tartaguti/ui-components";
+
+// Or per component, so the bundle only carries what you touched.
+import "@tartaguti/ui-components/tt-button";
+import "@tartaguti/ui-components/tt-data-table";
+```
+
+**Importing is registration.** There is no `register()` call. Importing
+the module runs `@customElement`, which defines the tag. This is why
+`sideEffects` is `true` in the manifest and must never be set to `false`:
+a bundler that "helpfully" drops an import with no used export would
+silently remove the component.
+
+## Use
+
+```html
+<tt-button variant="primary">Save</tt-button>
+
+<tt-data-table
+  selectable
+  .columns="${columns}"
+  .rows="${rows}"
+  @tt-sort="${onSort}"
+></tt-data-table>
+```
+
+Two things that trip people up, both consequences of these being real DOM
+elements rather than framework components:
+
+- **Objects and arrays go through properties, not attributes.** In Lit
+  that is the `.` prefix (`.rows=${rows}`). Elsewhere,
+  `el.rows = rows` in script. An attribute can only ever be a string.
+- **Attribute names are kebab-case.** The `buttonLabel` property is the
+  `button-label` attribute. Writing `buttonLabel` in HTML does nothing:
+  HTML lowercases it to `buttonlabel`, which is not an attribute here.
+
+## Your first screen, start to finish
+
+A new Vite app, one form, working in a few minutes:
+
+```bash
+npm create vite@latest my-app -- --template vanilla-ts
+cd my-app
+npm install @tartaguti/ui-components lit
+```
+
+```ts
+// src/main.ts
+import "@tartaguti/ui-components/tokens.css";
+import "@tartaguti/ui-components/tt-card";
+import "@tartaguti/ui-components/tt-input";
+import "@tartaguti/ui-components/tt-button";
+
+document.querySelector("#app")!.innerHTML = `
+  <tt-card heading="Sign in" description="Use your work email.">
+    <form id="login">
+      <tt-input name="email" type="email" label="Email" required full-width></tt-input>
+      <tt-button type="submit" variant="primary">Continue</tt-button>
+    </form>
+  </tt-card>
+`;
+
+// Form controls submit like native ones: read them with FormData.
+document.querySelector("#login")!.addEventListener("submit", (event) => {
+  event.preventDefault();
+  const data = new FormData(event.target as HTMLFormElement);
+  console.log(data.get("email"));
+});
+```
+
+`npm run dev`, and it is themed, dark-mode ready and keyboard accessible.
+
+## Events
+
+Every component speaks in `tt-*` events that bubble and cross shadow
+roots, with the whole new state in `detail`:
+
+```ts
+select.addEventListener("tt-change", (event) => console.log(event.detail.value));
+```
+
+The docs page of each component lists its events and their `detail`.
+
+## In a framework
+
+- **React 19 and later** passes properties and `on`-prefixed custom
+  events straight to custom elements: `<tt-select options={options}
+  ontt-change={(e) => setValue(e.detail.value)} />`. On React 18, set
+  arrays with a ref and use `addEventListener`.
+- **Vue**: tell the compiler which tags are custom elements
+  (`compilerOptions.isCustomElement: (tag) => tag.startsWith("tt-")`),
+  then `:options.prop="options"` and `@tt-change="..."`.
+- **Svelte**: works as is: `<tt-select options={options}
+  on:tt-change={handle} />` (Svelte 5: `ontt-change`).
+- **Plain HTML**: import the modules from a bundler, or from a CDN that
+  serves npm packages as ES modules.
+
+## Themes
+
+```html
+<html data-theme="soft">
+```
+
+`soft`, `sharp`, `editorial` and `bold` restyle corners, shadows and
+type together; `neutral` resets to the default. Themes compose with dark
+mode and density, and can be set on any element to theme one area.
+
+## Dark mode
+
+Put `class="dark"` on `<html>`. Nothing else. Design tokens are inherited
+custom properties, so they cross shadow boundaries on their own and every
+component follows.
+
+## Theming
+
+Override any `--tt-*` token on `:root`, or on any subtree:
+
+```css
+:root {
+  --tt-primary: oklch(0.55 0.2 260);
+  --tt-radius: 0.75rem;
+}
+```
+
+The palette ships neutral on purpose so it does not fight your brand.
+
+## Density and touch
+
+```html
+<html data-density="compact">
+```
+
+`compact` and `spacious` remap the spacing and control-height tokens, so
+every component tightens or loosens together. Touch devices get larger
+controls automatically via `pointer: coarse`; you do not opt in.
+
+## Before publishing a change
+
+```bash
+npm run build
+npm test
+npm run verify
+```
+
+`verify` packs the library, installs the tarball into a throwaway project
+with no workspace, and resolves every entry point the way a stranger
+would. It exists because the manifest once pointed at `src` while the
+tarball shipped only `dist`: install succeeded and the first import
+failed, and nothing inside the monorepo could catch it, because here the
+bare specifier resolves through the workspace symlink and never touches
+the tarball.
+
+## Versions
+
+The library is 0.x while its API settles: a minor version (0.2 to 0.3)
+may change an API, and the changelog says how to move. Patch versions
+only fix things.
+
+## Licence
+
+MIT. The icon shapes come from Lucide (ISC) and Feather (MIT); their
+notices ship in `THIRD-PARTY-NOTICES.md`.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,29 @@
+# Third-party notices
+
+## Lucide
+
+Most icon shapes in `src/tt-icon.ts` are taken or adapted from Lucide
+(https://lucide.dev), which is distributed under the ISC License below.
+
+ISC License
+
+Copyright (c) for portions of Lucide are held by Cole Bemis 2013-2022 as part of Feather (MIT). All other copyright (c) for Lucide are held by Lucide Contributors 2022.
+
+Permission to use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted, provided that the above copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+
+## Feather
+
+The Lucide portions above that come from Feather (https://feathericons.com)
+are under the MIT License.
+
+The MIT License (MIT)
+
+Copyright (c) 2013-2023 Cole Bemis
+
+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.