@inizioevoke/astro-core 2.2.2 → 2.2.4

package/agents/claude/astro-core/SKILL.md

@@ -0,0 +1,361 @@
+---
+name: astro-core
+description: >
+  Reference and implementation guide for @inizioevoke/astro-core — a library of reusable Astro components,
+  build integrations, and client-side gesture scripts. Use this skill whenever the user asks how to use,
+  add, configure, or troubleshoot anything from this library. Triggers on: component names (CssBackgroundImage,
+  CssVariables, FlipCard, RightISI, Modal, ModalTrigger, PdfViewer, ScrollContainer, Tabs, TabItem, Zoom),
+  integration names (pruneBuild, relativeLinks), script names (createSwipeListener, createPinchListener),
+  the package name @inizioevoke/astro-core, or any request to add/use one of these items in an Astro or
+  TypeScript file. Do NOT wait for the user to explicitly name the package — if they're working on an Astro
+  project and ask about a flip card, ISI panel, modal, PDF viewer, scroll container, tabs, or swipe/pinch
+  gesture, consult this skill.
+---
+
+# @inizioevoke/astro-core
+
+A library of reusable Astro components, build integrations, and client-side scripts for Evoke projects.
+
+**Install:** `npm install @inizioevoke/astro-core`
+
+## Behavior guide
+
+- For a general "how do I use X" question — answer from the quick-reference below (import path, key props, basic example).
+- If the user asks about specific props, all available slots, CSS variables, or the full JS API — read the relevant doc file (paths listed in each section) and answer from it.
+- When adding to a file — use the correct import path, include required props, and add relevant slots.
+
+---
+
+## Export paths
+
+| What | Import from |
+|---|---|
+| All Astro components | `@inizioevoke/astro-core` |
+| Build integrations | `@inizioevoke/astro-core/integrations` |
+| FlipCard JS lib | `@inizioevoke/astro-core/lib/FlipCard` |
+| ISI JS lib | `@inizioevoke/astro-core/lib/ISI` |
+| Modal JS lib | `@inizioevoke/astro-core/lib/Modal` |
+| PdfViewer JS lib | `@inizioevoke/astro-core/lib/PdfViewer` |
+| ScrollContainer JS lib | `@inizioevoke/astro-core/lib/ScrollContainer` |
+| Gesture scripts | `@inizioevoke/astro-core/lib/gestures` |
+
+---
+
+## Components
+
+### CssBackgroundImage
+
+Renders a `<style>` tag that sets `background-image` on a CSS selector. Optimizes images via Astro's `getImage` (webp, quality 80 by default). Supports responsive breakpoints via media queries. No client JS.
+
+```astro
+---
+import { CssBackgroundImage } from '@inizioevoke/astro-core';
+import heroImg from '../assets/hero.jpg';
+---
+<CssBackgroundImage image={heroImg} selector=".hero" size="cover" position="center" />
+```
+
+Key props: `image` (ImageMetadata, required), `selector` (default `body`), `size`, `position`, `repeat`, `optimize`, `format`, `quality`, `width`, `height`, `breakpoints[]`
+
+> For full prop details and breakpoint examples → read `docs/components/CssBackgroundImage.md`
+
+---
+
+### CssVariables
+
+Injects CSS custom properties (`--name: value`) into a selector. Supports `image` (optimized), `url`, or plain string/number values. Supports responsive breakpoints.
+
+```astro
+---
+import { CssVariables } from '@inizioevoke/astro-core';
+import bg from '../assets/bg.jpg';
+---
+<CssVariables
+  selector=":root"
+  variables={[
+    { name: '--brand-color', value: '#ff0000' },
+    { name: '--hero-bg', type: 'image', value: bg },
+  ]}
+/>
+```
+
+Key props: `selector` (default `:root`), `variables[]` (each with `name`, `value`, optional `type`, optional `breakpoints`)
+
+> For full variable type options and breakpoint examples → read `docs/components/CssVariables.md`
+
+---
+
+### FlipCard
+
+A 3D CSS flip card rendered as the `<evo-flip-card>` custom element. Uses `front` and `back` slots.
+
+```astro
+---
+import { FlipCard } from '@inizioevoke/astro-core';
+---
+<FlipCard width={300} height={200}>
+  <div slot="front">Front content</div>
+  <div slot="back">Back content</div>
+  <button slot="trigger">Flip</button>
+</FlipCard>
+```
+
+Slots: `front`, `back`, `trigger`, `front-trigger`, `back-trigger`
+Props: `width?`, `height?`, plus any `div` HTML attributes
+
+**Client-side JS** (in a `<script>` block):
+```ts
+import type { EvoFlipCardElement } from '@inizioevoke/astro-core/lib/FlipCard';
+const card = document.querySelector('evo-flip-card') as EvoFlipCardElement;
+card.toggle(); // or flipFront() / flipBack()
+```
+
+> For full CSS variable list and JS API details → read `docs/components/FlipCard.md`
+
+---
+
+### RightISI
+
+A sticky ISI (Important Safety Information) right-side drawer rendered as `<evo-isi>`. Embeds a `ScrollContainer` internally.
+
+```astro
+---
+import { RightISI } from '@inizioevoke/astro-core';
+---
+<RightISI transitionDuration={400} headerButton>
+  <div slot="header">ISI Title</div>
+  <p>Important safety information content goes here.</p>
+</RightISI>
+```
+
+Slots: `header`, `header-button`, `footer`, default (body content)
+Props: `transitionDuration?` (ms, default 500), `headerButton?` (boolean), `scrollContainer?` (ScrollContainerProps)
+
+**Client-side JS**:
+```ts
+import type { EvoIsiElement } from '@inizioevoke/astro-core/lib/ISI';
+const isi = document.querySelector('evo-isi') as EvoIsiElement;
+await isi.expand(); // toggle() / collapse() also available — all return Promise<void>
+```
+
+> For full slot and prop details → read `docs/components/ISI/RightISI.md` (if available) or check the source
+
+---
+
+### Modal
+
+A modal system with `<evo-modal>`, `ModalTrigger`, and `ModalOverlay` components. Supports `fade` and `none` animations.
+
+```astro
+---
+import { Modal, ModalTrigger } from '@inizioevoke/astro-core';
+---
+<ModalTrigger modal="my-modal" animation="fade">Open</ModalTrigger>
+
+<Modal id="my-modal" closeButton="default">
+  <h2>Modal Title</h2>
+  <p>Modal content here.</p>
+</Modal>
+```
+
+**Modal props:** `id` (required), `closeButton` (`'default'|'minimal'|'none'|false`), `closeButtonAtts`
+**ModalTrigger props:** `modal` (id, required), `animation?`
+Slots: default (inside wrapper), `close` (close button label), `outer` (full-bleed outside wrapper)
+
+**Client-side JS**:
+```ts
+import { showModal, hideModal, hideModals } from '@inizioevoke/astro-core/lib/Modal';
+showModal('#my-modal');
+hideModal('#my-modal', 'fade');
+```
+
+Custom events: `evomodal-visible`, `evomodal-hidden` (both bubble + composed)
+
+> For full CSS variable list, all JS functions, and data attributes → read `docs/components/Modal.md`
+
+---
+
+### PdfViewer
+
+A full-featured PDF viewer rendered as `<evo-pdf-viewer>`. Uses a bundled copy of pdf.js. Features lazy page rendering, pinch-to-zoom, toolbar, and vertical/horizontal layout.
+
+```astro
+---
+import { PdfViewer } from '@inizioevoke/astro-core';
+---
+<PdfViewer id="viewer" pdf="/documents/file.pdf" height="600px" theme="light" />
+```
+
+Props: `id` (required), `pdf` (URL, required), `height?`, `theme?` (`'light'|'dark'|'black'`), `zoom?`, `page?`, `layout?` (`'vertical'|'horizontal'`), `fit?`, `quality?`, `toolbar?`
+
+**Client-side JS**:
+```ts
+import type { EvoPdfViewerElement } from '@inizioevoke/astro-core/lib/PdfViewer';
+const viewer = document.querySelector('evo-pdf-viewer') as EvoPdfViewerElement;
+viewer.scrollToPage(3);
+viewer.zoom(1); // 1 = zoom in, -1 = zoom out, 0 = reset
+```
+
+Custom event: `evopdfviewer-click` (fires when a custom `http://pdfviewer.evo` protocol link is clicked)
+
+> For full prop details, fit modes, and toolbar options → read `docs/components/PdfViewer.md` (if available) or source
+
+---
+
+### ScrollContainer
+
+Wraps content in `<evo-scroll-container>` with a custom draggable scrollbar. Supports `vertical`, `horizontal`, or `both` axes.
+
+```astro
+---
+import { ScrollContainer } from '@inizioevoke/astro-core';
+---
+<ScrollContainer height="400px" scrolling="vertical">
+  <p>Long scrollable content here...</p>
+</ScrollContainer>
+```
+
+Props: `width?`, `height?`, `scrolling?` (default `'vertical'`), plus any `div` attributes
+
+**Client-side JS**:
+```ts
+import { scroll, refresh, getScroll } from '@inizioevoke/astro-core/lib/ScrollContainer';
+scroll('evo-scroll-container', { top: 0 });
+refresh(); // recalculate all scroll containers
+```
+
+> For full CSS variable list, element API, and all utility functions → read `docs/components/ScrollContainer.md`
+
+---
+
+### Tabs + TabItem
+
+Build-time tabbed panels. `Tabs` processes its slot at build time, extracting metadata from `TabItem` children to generate the tab list and panels.
+
+```astro
+---
+import { Tabs, TabItem } from '@inizioevoke/astro-core';
+---
+<Tabs>
+  <TabItem active>
+    <span slot="title">Tab One</span>
+    <p>Content for tab one.</p>
+  </TabItem>
+  <TabItem>
+    <span slot="title">Tab Two</span>
+    <p>Content for tab two.</p>
+  </TabItem>
+</Tabs>
+```
+
+**Tabs props:** `listType?` (`'ul'|'none'`)
+**TabItem props:** `active?`, `tabAttrs?`, `panelAttrs?`
+**TabItem slots:** `title`, default (panel content)
+
+> For full styling details → read `docs/components/Tabs.md`
+
+---
+
+### Zoom
+
+A convenience wrapper combining a content card with a `ModalTrigger` button and a `Modal`. Auto-generates the modal ID.
+
+```astro
+---
+import { Zoom } from '@inizioevoke/astro-core';
+---
+<Zoom animation="fade" modalIncludeTitle modalIncludeFooter>
+  <div slot="content">Card preview content</div>
+  <span slot="trigger">View full</span>
+  <div slot="modal-content">Full modal content here</div>
+</Zoom>
+```
+
+Slots: `content`, `trigger`, `header`, `footer`, `modal-header`, `modal-content`, `modal-footer`
+Props: `animation?`, `modalIncludeTitle?` (default true), `modalIncludeFooter?` (default true), `modalSlot?`
+
+---
+
+## Integrations
+
+### pruneBuild
+
+Deletes unreferenced asset files after build by scanning HTML/CSS/JS output for filename references.
+
+```ts
+// astro.config.mjs
+import { pruneBuild } from '@inizioevoke/astro-core/integrations';
+
+export default defineConfig({
+  integrations: [
+    pruneBuild({ keep: ['favicon.ico', /fonts\//] })
+  ]
+});
+```
+
+Options: `enabled?` (boolean), `keep?` (array of strings or RegExp)
+
+> For behavior details and edge cases → read `docs/integrations/prune-build.md`
+
+---
+
+### relativeLinks
+
+Rewrites absolute asset paths in `.html` and `.css` build output to relative paths (relative to each file's location). Useful for static deployments without a fixed root.
+
+```ts
+// astro.config.mjs
+import { relativeLinks } from '@inizioevoke/astro-core/integrations';
+
+export default defineConfig({
+  integrations: [relativeLinks()]
+});
+```
+
+Options: `enabled?` (default true)
+
+> For details on which attributes/properties are rewritten → read `docs/integrations/relative-links.md`
+
+---
+
+## Client-side gesture scripts
+
+Use inside Astro `<script>` blocks or in `.ts` client files.
+
+### createSwipeListener
+
+```ts
+import { createSwipeListener } from '@inizioevoke/astro-core/lib/gestures';
+
+const swipe = createSwipeListener(({ direction, distance, duration }) => {
+  if (direction === 'left') nextSlide();
+});
+
+// threshold can be '1/4', '1/3', '1/2' (fraction of screen) or a pixel number
+const swipe = createSwipeListener(handler, { threshold: '1/3' });
+
+swipe.disable();
+swipe.enable();
+swipe.dispose(); // remove listeners entirely
+```
+
+> For all threshold options and handler argument details → read `docs/lib/swipe.md`
+
+---
+
+### createPinchListener
+
+```ts
+import { createPinchListener } from '@inizioevoke/astro-core/lib/gestures';
+
+const pinch = createPinchListener((scale, gesture) => {
+  // gesture is 'pinch' or 'spread'
+  element.style.transform = `scale(${scale})`;
+});
+
+pinch.disable();
+pinch.enable();
+pinch.dispose();
+```
+
+> For cumulative scale behavior details → read `docs/lib/pinch.md`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inizioevoke/astro-core",
-  "version": "2.2.2",
+  "version": "2.2.4",
   "description": "",
   "license": "ISC",
   "author": "",
@@ -17,10 +17,15 @@
     "./lib/ScrollContainer": "./src/components/ScrollContainer/index.ts",
     "./lib/gestures": "./src/lib/gestures/index.ts"
   },
+  "scripts": {
+    "postinstall": "node postinstall.mjs"
+  },
   "files": [
+    "agents",
     "docs",
     "src",
-    "index.ts"
+    "index.ts",
+    "postinstall.mjs"
   ],
   "peerDependencies": {
     "astro": ">=5.0.0",

package/postinstall.mjs

@@ -0,0 +1,18 @@
+import { copyFileSync, mkdirSync, existsSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Resolve the consuming project's root (three levels up from node_modules/@inizioevoke/astro-core)
+const projectRoot = join(__dirname, '..', '..', '..');
+const destDir = join(projectRoot, '.claude', 'skills');
+const src = join(__dirname, 'agents', 'claude', 'astro-core', 'SKILL.md');
+const dest = join(destDir, 'inizioevoke-astro-core.md');
+
+if (!existsSync(destDir)) {
+  mkdirSync(destDir, { recursive: true });
+}
+
+copyFileSync(src, dest);
+console.log(`[@inizioevoke/astro-core] Copied skill to ${dest}`);

package/src/components/CssBackgroundImage.astro

@@ -50,8 +50,8 @@ async function getImageSrc({image, format, quality, width, height, optimize}: Im
   if (optimize !== false) {
     const img = await getImage({
       src: image,
-      format: format ?? image.format,
-      quality: quality,
+      format: format ?? 'webp',
+      quality: quality ?? 80,
       width,
       height
     });

package/src/components/CssVariables.astro

@@ -80,8 +80,8 @@ async function createVariable(v: CssImageVariable | CssVariable) {
       if (iv.optimize !== false) {
         const img = await getImage({
           src: iv.value,
-          format: iv.format ?? iv.value.format,
-          quality: iv.quality,
+          format: iv.format ?? 'webp',
+          quality: iv.quality ?? 80,
           width: iv.width,
           height: iv.height
         });