@ssejal8/recipe-ui-kit 0.1.0 → 0.1.1

package/README.md

@@ -1,354 +1,185 @@
-# Recipe Finder & Meal Planner
+# @ssejal8/recipe-ui-kit
 
-A recipe discovery and weekly meal-planning application built with **Svelte 5 + SvelteKit**, using a **StencilJS** web component library that is published to npm and consumed as a package dependency.
+Framework-agnostic web components for recipe discovery, favorites and meal-planning UIs, built with [StencilJS](https://stenciljs.com/).
 
-| | |
-| --- | --- |
-| **Live application** | _fill in after deploying — see [Deployment](#deployment)_ |
-| **npm package** | https://www.npmjs.com/package/recipe-kit-stencil |
-| **GitHub repository** | _fill in after pushing — see [Repository](#repository)_ |
-| **Recipe data** | [TheMealDB](https://www.themealdb.com/api.php) (public test key, no signup) |
-
----
-
-## Contents
-
-- [What it does](#what-it-does)
-- [Repository layout](#repository-layout)
-- [Setup](#setup)
-- [Starting the development server](#starting-the-development-server)
-- [The Stencil component library](#the-stencil-component-library)
-- [Publishing to npm](#publishing-to-npm)
-- [How SvelteKit consumes the package](#how-sveltekit-consumes-the-package)
-- [Architecture](#architecture)
-- [Deployment](#deployment)
-- [Repository](#repository)
-- [Assumptions and decisions](#assumptions-and-decisions)
-- [Known limitations](#known-limitations)
-
----
-
-## What it does
-
-**Recipe discovery** — Search the catalogue by name, browse by category chip, and narrow results by category, cuisine and main ingredient. Every filter lives in the URL, so a search is shareable and survives a reload. Results can be sorted, and are paged client-side.
-
-**Recipe details** — A dedicated page per recipe with the full ingredient list (as a tickable prep checklist with progress), numbered method steps, cuisine metadata, and links to the original source and video where the API provides them.
-
-**Recipe management** — Create, edit and delete your own recipes through a validated form. Your recipes are searchable alongside the catalogue, appear first in results, and are marked with a badge. Deletes are undoable.
-
-**Favorites** — Favorite from any card or from the detail page, filter your saved list by text and category, and clear the list (also undoable).
-
-**Weekly meal planner** — A 7-day × 3-meal grid for any week, with previous/next week navigation, "repeat last week", drag-and-drop between slots, a recipe picker that searches your favorites / your own recipes / the whole catalogue, and a per-week recipe summary.
-
-Favorites, your recipes and meal plans persist in `localStorage` and stay in sync across duplicate browser tabs.
-
----
-
-## Repository layout
+The library ships **standard custom elements**, so it works in SvelteKit, React, Vue, Angular or plain HTML with no framework-specific wrapper. It is consumed by the [Recipe Finder & Meal Planner](https://github.com/sejal-sharma/recipe-ui) SvelteKit application.
 
 ```
-recipe-ui/                          npm workspaces root
-├── packages/
-│   └── recipe-kit-stencil/         StencilJS component library → published to npm
-│       ├── src/components/         10 web components (.tsx + .css + specs)
-│       ├── src/global/             design tokens (--rk-* custom properties)
-│       ├── src/index.html          component gallery / dev harness
-│       └── stencil.config.ts
-└── apps/
-    └── recipe-web/                 SvelteKit 5 application
-        ├── src/lib/api/            typed TheMealDB client
-        ├── src/lib/domain/         recipe model + validation rules
-        ├── src/lib/stencil/        the SvelteKit ↔ Stencil integration layer
-        ├── src/lib/stores/         Svelte 5 rune stores, localStorage-backed
-        ├── src/lib/components/     app-level Svelte components
-        └── src/routes/             pages
+npm install @ssejal8/recipe-ui-kit
 ```
 
 ---
 
-## Setup
-
-**Requirements:** Node.js ≥ 20 and npm ≥ 10.
-
-```bash
-git clone <your-repo-url> recipe-ui
-cd recipe-ui
-npm install
-```
-
-A single `npm install` at the root installs both workspaces. The component library's `prepare` script builds it automatically, so the app has something to import straight away.
+## Quick start
 
-No environment variables and no API key are needed — TheMealDB's public test key is used.
+### 1. Register the elements
 
----
-
-## Starting the development server
+```js
+import { defineCustomElements } from '@ssejal8/recipe-ui-kit/loader';
 
-```bash
-npm run dev
+defineCustomElements();
 ```
 
-Builds the component library, then starts the app on **http://localhost:5173**.
+`defineCustomElements()` registers every tag lazily — the code for a component is only fetched when that tag first appears in the DOM.
 
-Other useful commands, all from the repository root:
+### 2. Load the design tokens
 
-| Command | What it does |
-| --- | --- |
-| `npm run dev` | Build the library, then run the app dev server |
-| `npm run dev:app` | App dev server only (library already built) |
-| `npm run dev:kit` | Library in watch mode + component gallery |
-| `npm run build` | Production build of the library, then the app |
-| `npm run check` | `svelte-check` type and template checking |
-| `npm test` | Component library spec tests |
-| `npm run publish:kit` | Publish the library to npm |
+```js
+import '@ssejal8/recipe-ui-kit/dist/recipe-kit/recipe-kit.css';
+```
 
-Working on a component and the app at the same time? Run `npm run dev:kit` and `npm run dev:app` in two terminals — Stencil rebuilds `dist/` on save and Vite picks it up.
+This stylesheet defines the `--rk-*` custom properties. Because custom properties inherit through the shadow boundary, it is the single place to re-theme the whole library.
 
-To verify a real production server locally:
+### 3. Use the elements
 
-```bash
-npm run build:kit
-npm run preview:node --workspace recipe-web    # builds with adapter-node and serves it
+```html
+<rk-recipe-card
+  recipe-id="52772"
+  name="Teriyaki Chicken Casserole"
+  image="https://…/teriyaki.jpg"
+  category="Chicken"
+  area="Japanese"
+  minutes="45"
+>
+  <rk-badge tone="accent" small>weeknight</rk-badge>
+  <button slot="actions">Add to plan</button>
+</rk-recipe-card>
 ```
 
----
-
-## The Stencil component library
+### SSR / SvelteKit note
 
-`recipe-kit-stencil` ships 10 framework-agnostic custom elements. Full prop / event / slot tables are in [`packages/recipe-kit-stencil/README.md`](./packages/recipe-kit-stencil/README.md) and in the generated docs beside each component.
+Custom elements are a browser API, so registration must happen on the client only:
 
-| Tag | Role in the app | Events consumed by SvelteKit |
-| --- | --- | --- |
-| `rk-recipe-card` | Every recipe tile, in all grids | `rkCardSelect`, `rkFavoriteToggle` |
-| `rk-search-bar` | Discover, favorites, my recipes, picker | `rkSearch`, `rkClear` |
-| `rk-chip` | Category rail, active-filter pills, favorites facets | `rkChipToggle`, `rkChipDismiss` |
-| `rk-segmented-control` | Sort controls, picker source switch | `rkSegmentChange` |
-| `rk-meal-slot` | All 21 cells of the planner grid | `rkMealAdd`, `rkMealSwap`, `rkMealRemove`, `rkMealOpen`, `rkMealDrop` |
-| `rk-modal` | Picker, add-to-plan, all confirmations | `rkModalClose` |
-| `rk-tag-input` | Tag field in the recipe form | `rkTagsChange` |
-| `rk-badge` | Metadata badges throughout | — |
-| `rk-rating` | Star rating display | `rkRatingChange` |
-| `rk-empty-state` | Every empty and error state | — |
-
-Run the gallery to see and exercise all of them, with a live event log:
+```svelte
+<script>
+  import { browser } from '$app/environment';
+  import { onMount } from 'svelte';
 
-```bash
-npm run dev:kit          # → http://localhost:3333
+  onMount(async () => {
+    const { defineCustomElements } = await import('@ssejal8/recipe-ui-kit/loader');
+    await defineCustomElements();
+  });
+</script>
 ```
 
-### Design principles
-
-- **Primitive props over object props.** `rk-recipe-card` takes `name`, `image`, `category` … as separate primitives rather than one `recipe` object, so it works from plain HTML attributes in any framework.
-- **Components are controlled.** They emit intent and never mutate their own state. `rkFavoriteToggle` reports the state to move *to*; the app persists it and passes `favorite` back down.
-- **Shadow DOM everywhere.** Styling hooks are deliberate: `--rk-*` custom properties and `part="…"` attributes.
-- **Complex props have a string fallback.** `options` and `values` are arrays, assigned as DOM properties on the normal path, but both also parse a JSON string attribute.
+Unknown tags render as inert elements during SSR and hydrate once the definitions land.
 
 ---
 
-## Publishing to npm
+## Components
 
-The library is configured to publish to the public registry regardless of any local registry setting, via `publishConfig` in its `package.json`.
-
-```bash
-# 1. Log in to the public npm registry (once per machine)
-npm login --registry=https://registry.npmjs.org/
+| Tag | Purpose | Key events |
+| --- | --- | --- |
+| `<rk-search-bar>` | Debounced search field with clear button and an `actions` slot | `rkSearch`, `rkClear` |
+| `<rk-chip>` | Selectable / dismissible filter chip | `rkChipToggle`, `rkChipDismiss` |
+| `<rk-segmented-control>` | Single-select segmented control (sorting, view switching) | `rkSegmentChange` |
+| `<rk-recipe-card>` | Recipe tile with favorite toggle, badges slot and actions slot | `rkCardSelect`, `rkFavoriteToggle` |
+| `<rk-rating>` | Star rating, read-only or interactive | `rkRatingChange` |
+| `<rk-badge>` | Small slot-driven label with tone/variant options | — |
+| `<rk-tag-input>` | Tag / token editor with de-duplication and a max-tags cap | `rkTagsChange` |
+| `<rk-meal-slot>` | One planner cell: add target, filled slot, and drop zone | `rkMealAdd`, `rkMealSwap`, `rkMealRemove`, `rkMealOpen`, `rkMealDrop` |
+| `<rk-modal>` | Accessible dialog with focus trap, Escape handling and slots | `rkModalClose` |
+| `<rk-empty-state>` | Empty / error placeholder with an actions slot | — |
+
+Per-component prop, event, slot and CSS-part tables are generated from source into each component folder — see [`src/components`](./src/components).
 
-# 2. Publish from the repository root
-npm run publish:kit
-```
+---
 
-`prepublishOnly` runs a clean production build first, so a published tarball can never contain stale output. `files` is restricted to `dist/`, `loader/`, `README.md` and `LICENSE` — no source, no tests, no config.
+## Design principles
 
-### Versioning
+**Primitive props over object props.** `<rk-recipe-card>` takes `name`, `image`, `category` … as separate primitive properties rather than one `recipe` object. Primitives round-trip through HTML attributes, so the component is usable from plain markup in any framework.
 
-[Semantic versioning](https://semver.org/), from the library directory:
+**Complex props accept a string fallback.** `rk-segmented-control.options` and `rk-tag-input.values` are arrays. Assign them as DOM properties for the normal path; both also parse a JSON-encoded (or comma-separated) string attribute for consumers that cannot set properties.
 
-| Change | Command |
-| --- | --- |
-| Bug fix, styling correction, no API change | `npm run release:patch` |
-| New component, new optional prop, new event | `npm run release:minor` |
-| Renamed/removed prop, event or tag; changed payload | `npm run release:major` |
+**Components are controlled.** They emit an intent and let the host application own the state. `rkFavoriteToggle` reports the state to move *to*; the app persists it and passes `favorite` back down. Nothing is silently mutated behind the application's back.
 
-Each script bumps the version, then publishes. After a bump, raise the range in `apps/recipe-web/package.json` to match.
+**No global CSS leakage.** Every component uses shadow DOM. Styling hooks are exposed deliberately, via `--rk-*` custom properties and `part="…"` attributes.
 
 ---
 
-## How SvelteKit consumes the package
+## Theming
 
-The app depends on the library **by package name**, exactly as any external consumer would:
+Override any token on `:root` — or on any ancestor, to scope a theme to a subtree:
 
-```jsonc
-// apps/recipe-web/package.json
-"dependencies": {
-  "recipe-kit-stencil": "^0.1.0"
+```css
+:root {
+  --rk-primary: #7c3aed;
+  --rk-radius-lg: 8px;
+  --rk-font-display: 'Fraunces', serif;
 }
 ```
 
-Nothing is imported from `packages/recipe-kit-stencil/src`. All imports resolve through the package's `exports` map to its built `dist/` and `loader/` output:
-
-```ts
-import 'recipe-kit-stencil/dist/recipe-kit/recipe-kit.css';        // design tokens
-const { defineCustomElements } = await import('recipe-kit-stencil/loader');
-```
-
-Because both directories are npm workspaces, `npm install` satisfies `^0.1.0` from the local package during development — one install, no `npm link`, no manual rebuild step. Outside this repository the identical range resolves from the registry.
-
-To prove the registry path end-to-end after publishing:
-
-```bash
-cd /tmp && mkdir kit-check && cd kit-check && npm init -y
-npm install recipe-kit-stencil --registry=https://registry.npmjs.org/
-ls node_modules/recipe-kit-stencil/loader
-```
-
-### Passing data down: properties, not attributes
+A dark palette is included and activates on `<html data-rk-theme="dark">` (or `data-theme="dark"`).
 
-Attributes can only carry strings, so array props such as `rk-segmented-control.options` must be assigned as DOM properties. `src/lib/stencil/WebComponent.svelte` is a small bridge that handles this for the whole app:
+For finer control, target the exposed shadow parts:
 
-```svelte
-<WebComponent
-  tag="rk-recipe-card"
-  props={{ recipeId: recipe.id, name: recipe.name, favorite: isFavorite }}
-  events={{ rkFavoriteToggle: handleToggle }}
->
-  <rk-badge tone="accent" small>30 min</rk-badge>
-  {#snippet actions()}
-    <button slot="actions" class="btn btn-sm">Add to plan</button>
-  {/snippet}
-</WebComponent>
-```
-
-It does three things that matter:
-
-1. **Defers property writes until the element upgrades.** Assigning a property before `customElements.define` runs would shadow the generated accessor, so writes wait on `customElements.whenDefined(tag)`.
-2. **Registers listeners with `addEventListener`.** The library emits `rkFavoriteToggle`, not `rkfavoritetoggle`; `addEventListener` preserves case exactly, keeping the app's contract identical to the library's documented one.
-3. **Mirrors props as kebab-case attributes for SSR.** Property assignment cannot happen on the server, which would leave every card an empty shell until hydration. Stencil observes attributes, so elements render with correct content in the server response — before hydration, and with JavaScript disabled.
-
-### Handling events coming back up
-
-Custom events are handled as ordinary app logic. The store is treated as the source of truth rather than the event payload, so a change made in another tab cannot be clobbered:
-
-```ts
-function handleFavoriteToggle(event: CustomEvent<{ favorite: boolean }>) {
-  const nowFavorite = favorites.toggle(recipe);
-  if (nowFavorite !== event.detail.favorite) return;
-  toasts.push(nowFavorite ? `Saved “${recipe.name}”.` : `Removed “${recipe.name}”.`);
+```css
+rk-recipe-card::part(title) {
+  text-transform: uppercase;
 }
 ```
 
-### Slots
-
-- **Default slot** — badges under a card title (`rk-recipe-card`), call-to-action buttons (`rk-empty-state`), dialog body (`rk-modal`).
-- **Named slots** — `actions` on `rk-recipe-card` for per-card buttons, `actions` on `rk-search-bar` for the result counter, `footer` on `rk-modal` for every confirmation's button row.
-
-Slotted content is passed with Svelte 5 snippets. Any element needing a `slot="…"` attribute must sit inside a `{#snippet}` block, because Svelte 5 treats `slot` on a direct child of a *component* as the deprecated slot syntax.
-
 ---
 
-## Architecture
+## Events
 
-### Data flow
+Every event name is prefixed `rk` and bubbles with `composed: true`, so it can be handled on an ancestor rather than each element:
 
+```js
+document.addEventListener('rkFavoriteToggle', (event) => {
+  const { recipeId, favorite } = event.detail;
+});
 ```
-TheMealDB ──► src/lib/api/mealdb.ts ──► +page.ts load ──► page component ──► rk-* elements
-                (typed, normalised)      (SSR + CSR)          │                    │
-                                                              │  props down        │  events up
-localStorage ──► rune stores ─────────────────────────────────┘◄───────────────────┘
-```
-
-**One recipe model.** TheMealDB returns 20 flat `strIngredient1…20` / `strMeasure1…20` column pairs, inconsistent instruction formatting, and comma-joined tags. `src/lib/api/mealdb.ts` normalises all of it into a single `Recipe` type that user-authored recipes also satisfy, so no component branches on data origin — only on whether the user *owns* a recipe.
-
-**Filters live in the URL.** Search state is read from `url.searchParams` inside `load`, which means SvelteKit re-runs the fetch on change and no fetch logic is duplicated in the component.
-
-**Combined filters via set intersection.** The API only supports one filter dimension per request, so each active filter becomes one `filter.php` call and the resulting id sets are intersected. That is what makes "Seafood + Italian" work.
-
-**Stores are classes with explicit persistence.** Stores are created at module scope, outside any component, where `$effect` has no owner — so each mutation calls `save()` rather than relying on an effect. A `storage` listener keeps duplicate tabs in sync.
-
-**Referential integrity is owned by the store, not the pages.** Favorites and planner slots hold a `RecipeSummary` snapshot so those views render without a network round-trip per recipe. `myRecipes.update()` and `.remove()` therefore propagate renames and deletions into favorites and every planned slot, so no caller can forget to.
 
-### Validation
-
-`src/lib/domain/validation.ts` is pure and Svelte-free, so the same rules could run on a server later. It enforces: required name (3–120 chars), required category and cuisine, valid `http(s)` image URL if given, ≥ 2 ingredients with no case-insensitive duplicates, ≥ 1 instruction step, optional whole-number time and servings within range, ≤ 6 tags, and a notes length cap. Duplicate recipe titles are checked separately, in the page, because that rule depends on store contents rather than input shape.
-
-Errors surface only after the first submit attempt, then live on every keystroke, with a count banner and focus moved to the first invalid field.
-
-### Rendering
-
-Discover, recipe details and the facet lists are server-rendered. Anything backed by `localStorage` — favorites, your recipes, the planner — is client-only by nature, and each page handles the pre-hydration window explicitly rather than flashing an incorrect empty state.
-
----
+Payload types are exported for TypeScript consumers:
 
-## Deployment
-
-`adapter-auto` is the default: on Vercel, Netlify or Cloudflare Pages it installs the right adapter with no configuration.
-
-### Vercel or Netlify (recommended)
-
-Import the repository, then set:
-
-| Setting | Value |
-| --- | --- |
-| Root directory / base | `apps/recipe-web` |
-| Install command | `npm install` |
-| Build command | `npm run build` |
-
-npm workspaces are detected from the repository root, so the install reaches both packages. Once the library is published, the app installs it from the registry and no library build step is needed at all.
-
-### Self-hosted Node
-
-```bash
-npm run build:kit
-ADAPTER=node npm run build --workspace recipe-web
-node apps/recipe-web/build/index.js          # PORT and HOST are respected
+```ts
+import type { RkFavoriteToggleDetail, RkMealDropDetail, RkSegmentOption } from '@ssejal8/recipe-ui-kit';
 ```
 
-Verified locally: the Node build boots and serves every route.
-
 ---
 
-## Repository
+## Local development
 
 ```bash
-git remote add origin https://github.com/<your-username>/recipe-ui.git
-git push -u origin main
+npm install
+npm start          # dev server with the component gallery at src/index.html
+npm run build      # production build + generated docs
+npm test           # spec tests
 ```
 
-Then fill in the repository and live-application links in the table at the top of this file.
+`npm start` serves a gallery page that renders every component and logs every emitted event — useful for verifying behaviour outside the consuming app.
 
 ---
 
-## Assumptions and decisions
-
-**TheMealDB was chosen over Spoonacular or Edamam** because it needs no API key or signup, which keeps the project clone-and-run. Consequences: it has no ratings, no cook times and no nutrition data, and no write endpoints.
+## Output targets
 
-**No backend, and user data is per-browser.** The assignment scopes the deliverable to the frontend, so favorites, user recipes and meal plans are stored in `localStorage`. They are therefore per-browser and per-device: they do not sync, and clearing site data clears them. A URL to a user-authored recipe only resolves in the browser that created it, which the detail page states explicitly rather than showing a bare 404.
-
-**Cook time and servings are only shown when they are real.** Rather than estimating a time for API recipes from instruction length, those fields are simply omitted for catalogue recipes and shown only for user-authored ones. Cards show ingredient count instead, which is genuine data.
-
-**The default Discover view is a small featured set.** `search.php` with an empty query returns 25 recipes, not the full catalogue. Rather than firing 14 parallel category requests on every page load, the default view is labelled "Featured recipes" and a category chip rail gives one-tap access to each full category list.
-
-**The planner is week-addressable.** Plans are keyed by the Monday of their week, so past and future weeks are all navigable and "repeat last week" is possible, rather than there being a single perpetual week.
-
-**Ratings are display-only.** `rk-rating` is fully interactive, but the app never persists a user rating: TheMealDB has no rating data to seed from, and a rating that exists only in one browser would be misleading. The component is in the library for completeness and is exercised in the gallery.
+| Target | Output | Use case |
+| --- | --- | --- |
+| `dist` | `dist/`, `loader/` | Lazy-loaded elements. The default, and what the SvelteKit app uses. |
+| `dist-custom-elements` | `dist/components/*.js` | Import and register a single component; tree-shakeable. |
 
-**The prep checklist is intentionally not persisted.** Ticking ingredients on the detail page is a cooking aid for the current session, not part of the recipe.
+```js
+// Single-component import
+import { RkRecipeCard } from '@ssejal8/recipe-ui-kit/components/rk-recipe-card';
+```
 
-**`recipe-kit-stencil` is unscoped.** The name was verified available on npm. Publishing under a scope instead only needs the `name` field changed in the library's `package.json` and the dependency in the app's.
+---
 
-**Node ≥ 20** is assumed, matching the SvelteKit 2 and Vite 8 baseline.
+## Versioning
 
----
+[Semantic versioning](https://semver.org/):
 
-## Known limitations
+- **patch** — bug fixes, styling corrections, no API change
+- **minor** — new components, new optional props, new events
+- **major** — renamed or removed props/events/tags, changed event payloads
 
-- **Deploy and publish are not done.** Both need credentials this environment does not have. The npm package is built, packed and verified (`npm pack` produces a valid tarball); the production Node build is verified booting and serving. The two links at the top of this file are the remaining steps.
-- **Browser interaction was not verified end-to-end.** Every route was exercised over HTTP and asserted on its server-rendered output (card counts, filter intersection, planner grid, 404 handling), `svelte-check` reports zero errors, and 16 component spec tests pass. Click-through of the drag-and-drop planner and the create/edit form was not machine-verified.
-- **Stencil's bundled test runner is deprecated** as of Stencil 4 and will be removed in v5. The spec tests will need migrating to `@stencil/vitest`.
-- **Ingredient filtering of your own recipes is a substring match**, while the API's ingredient filter is an exact match on its own ingredient vocabulary. Results from the two sources can differ in strictness for the same query.
-- **No pagination against the API.** TheMealDB returns whole result sets, so paging is client-side over the full list.
+```bash
+npm run release:patch   # or release:minor / release:major
+```
 
----
+`prepublishOnly` runs a clean production build, so a published tarball can never contain stale output.
 
 ## License
 
-MIT
+MIT © Sejal Sharma