@ssejal8/recipe-ui-kit 0.1.0

package/packages/recipe-kit-stencil/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sejal Sharma
+
+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/packages/recipe-kit-stencil/README.md

@@ -0,0 +1,185 @@
+# recipe-kit-stencil
+
+Framework-agnostic web components for recipe discovery, favorites and meal-planning UIs, built with [StencilJS](https://stenciljs.com/).
+
+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.
+
+```
+npm install recipe-kit-stencil
+```
+
+---
+
+## Quick start
+
+### 1. Register the elements
+
+```js
+import { defineCustomElements } from 'recipe-kit-stencil/loader';
+
+defineCustomElements();
+```
+
+`defineCustomElements()` registers every tag lazily — the code for a component is only fetched when that tag first appears in the DOM.
+
+### 2. Load the design tokens
+
+```js
+import 'recipe-kit-stencil/dist/recipe-kit/recipe-kit.css';
+```
+
+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.
+
+### 3. Use the elements
+
+```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>
+```
+
+### SSR / SvelteKit note
+
+Custom elements are a browser API, so registration must happen on the client only:
+
+```svelte
+<script>
+  import { browser } from '$app/environment';
+  import { onMount } from 'svelte';
+
+  onMount(async () => {
+    const { defineCustomElements } = await import('recipe-kit-stencil/loader');
+    await defineCustomElements();
+  });
+</script>
+```
+
+Unknown tags render as inert elements during SSR and hydrate once the definitions land.
+
+---
+
+## Components
+
+| 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).
+
+---
+
+## Design principles
+
+**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.
+
+**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.
+
+**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.
+
+**No global CSS leakage.** Every component uses shadow DOM. Styling hooks are exposed deliberately, via `--rk-*` custom properties and `part="…"` attributes.
+
+---
+
+## Theming
+
+Override any token on `:root` — or on any ancestor, to scope a theme to a subtree:
+
+```css
+:root {
+  --rk-primary: #7c3aed;
+  --rk-radius-lg: 8px;
+  --rk-font-display: 'Fraunces', serif;
+}
+```
+
+A dark palette is included and activates on `<html data-rk-theme="dark">` (or `data-theme="dark"`).
+
+For finer control, target the exposed shadow parts:
+
+```css
+rk-recipe-card::part(title) {
+  text-transform: uppercase;
+}
+```
+
+---
+
+## Events
+
+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;
+});
+```
+
+Payload types are exported for TypeScript consumers:
+
+```ts
+import type { RkFavoriteToggleDetail, RkMealDropDetail, RkSegmentOption } from 'recipe-kit-stencil';
+```
+
+---
+
+## Local development
+
+```bash
+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
+```
+
+`npm start` serves a gallery page that renders every component and logs every emitted event — useful for verifying behaviour outside the consuming app.
+
+---
+
+## Output targets
+
+| 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. |
+
+```js
+// Single-component import
+import { RkRecipeCard } from 'recipe-kit-stencil/components/rk-recipe-card';
+```
+
+---
+
+## Versioning
+
+[Semantic versioning](https://semver.org/):
+
+- **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
+
+```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 © Sejal Sharma