@inizioevoke/astro-core 2.1.2 → 2.2.1

package/docs/components/Tabs.md

@@ -0,0 +1,102 @@
+# Tabs
+
+The Tabs component renders a tabbed panel interface. Each tab is defined by a `TabItem` child component. `Tabs` processes its slot at build time, extracts tab metadata from each `TabItem`, and generates the tab list and panels from a single slot.
+
+## Components
+
+### `Tabs`
+
+The outer container that renders the tab list and panels.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `listType` | `'ul' \| 'none'` | `'ul'` | Controls the tab list element. `'ul'` wraps each tab button in an `<li>` (default); `'none'` renders buttons directly in a `<div>` |
+
+#### Slots
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | One or more `<TabItem>` components |
+
+---
+
+### `TabItem`
+
+Defines a single tab. Rendered as a child of `Tabs`. The tab button label comes from the `title` slot; the panel content comes from the default slot.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `active` | `true` | — | Marks this tab as the initially active one. Omit on all others. |
+| `tabAttrs` | `HTMLAttributes<'div'>` | — | Attributes spread onto the generated tab button. `title` here sets the button label as a fallback if the `title` slot is empty. |
+| `panelAttrs` | `HTMLAttributes<'div'>` | — | Attributes spread onto the panel `<div role="tabpanel">` |
+
+#### Slots
+
+| Slot | Description |
+|------|-------------|
+| `title` | The tab button label |
+| *(default)* | The panel content shown when this tab is active |
+
+---
+
+## Examples
+
+### Basic tabs
+
+```astro
+---
+import { Tabs, TabItem } from '@inizioevoke/astro-core';
+---
+<Tabs>
+  <TabItem active>
+    <span slot="title">First</span>
+    <p>Content for the first tab.</p>
+  </TabItem>
+  <TabItem>
+    <span slot="title">Second</span>
+    <p>Content for the second tab.</p>
+  </TabItem>
+  <TabItem>
+    <span slot="title">Third</span>
+    <p>Content for the third tab.</p>
+  </TabItem>
+</Tabs>
+```
+
+### Button-style tabs (`listType="none"`)
+
+Renders tab buttons in a `<div>` instead of a `<ul>/<li>` structure — useful when you want a button-bar style rather than a classic tabbed nav.
+
+```astro
+<Tabs listType="none">
+  <TabItem active>
+    <span slot="title">Overview</span>
+    <p>Overview content.</p>
+  </TabItem>
+  <TabItem>
+    <span slot="title">Details</span>
+    <p>Details content.</p>
+  </TabItem>
+</Tabs>
+```
+
+### Custom attributes on tabs and panels
+
+Use `tabAttrs` to add attributes to the tab button (e.g. `id`, `aria-*`), and `panelAttrs` to add attributes to the panel element.
+
+```astro
+<Tabs>
+  <TabItem
+    active
+    tabAttrs={{ id: 'tab-1', 'aria-controls': 'panel-1' }}
+    panelAttrs={{ id: 'panel-1' }}
+  >
+    <span slot="title">Tab One</span>
+    <p>Panel content.</p>
+  </TabItem>
+</Tabs>
+```

package/docs/integrations/prune-build.md

@@ -0,0 +1,75 @@
+# prune-build
+
+An Astro integration that removes unreferenced assets from the build output after `astro build` completes. It scans all `.css`, `.html`, and `.js` files in the output directory and deletes any asset whose filename does not appear in any of those files.
+
+## Usage
+
+```ts
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { pruneBuild } from '@inizioevoke/astro-core/integrations';
+
+export default defineConfig({
+  integrations: [pruneBuild()],
+});
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Set to `false` to skip pruning entirely. Useful for disabling conditionally (e.g. in dev/preview environments). |
+| `keep` | `(string \| RegExp)[]` | `[]` | Assets to retain even if unreferenced. Strings are matched by exact relative path; RegExps are tested against the relative path. |
+
+Relative paths are rooted at the build output directory and begin with `/` (e.g. `/_astro/logo.svg`).
+
+## How it works
+
+1. After the build completes, all non-HTML files in the output directory are collected as candidate assets.
+2. All `.css`, `.html`, and `.js` files are scanned for any occurrence of each asset's **filename** (basename only, no directory).
+3. Any asset whose filename is not found in any scanned file is deleted, unless it matches an entry in `opts.keep`.
+
+## Examples
+
+### Default — prune all unreferenced assets
+
+```ts
+integrations: [pruneBuild()]
+```
+
+### Retain specific files
+
+Use an exact relative path string to keep a specific file:
+
+```ts
+integrations: [
+  pruneBuild({
+    keep: ['/_astro/logo.svg'],
+  }),
+]
+```
+
+### Retain files matching a pattern
+
+Use a `RegExp` to keep a set of files by pattern:
+
+```ts
+integrations: [
+  pruneBuild({
+    keep: [/\/_astro\/fonts\//],
+  }),
+]
+```
+
+### Mix strings and patterns
+
+```ts
+integrations: [
+  pruneBuild({
+    keep: [
+      '/_astro/og-image.png',
+      /\/_astro\/icons\//,
+    ],
+  }),
+]
+```

package/docs/integrations/relative-links.md

@@ -0,0 +1,53 @@
+# relative-links
+
+An Astro integration that rewrites absolute asset paths in the build output to relative paths after `astro build` completes. This is useful when deploying to a subdirectory or when the final host path is unknown at build time.
+
+## Usage
+
+```ts
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import { relativeLinks } from '@inizioevoke/astro-core/integrations';
+
+export default defineConfig({
+  integrations: [relativeLinks()],
+});
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | `boolean` | `true` | Set to `false` to skip processing entirely. Useful for disabling conditionally (e.g. in dev/preview environments). |
+
+## How it works
+
+1. After the build completes, all `.html` and `.css` files in the output directory are collected.
+2. Each file is scanned for occurrences of the `base` path (from `astro.config.mjs`) in attribute values and `url()` expressions.
+3. Matching absolute references are replaced with a relative path calculated from the file's location up to the output root.
+
+### Where replacements are applied in HTML files
+
+- Attribute values: `href`, `src`, `srcset`, `poster`, `component-url`, `renderer-url`
+- Inline `style` attribute `url()` expressions
+- `<style>` block `url()` expressions
+
+### Where replacements are applied in CSS files
+
+- `url()` expressions
+
+## Examples
+
+### Default — rewrite all absolute paths
+
+```ts
+integrations: [relativeLinks()]
+```
+
+### Disable conditionally
+
+```ts
+integrations: [
+  relativeLinks({ enabled: process.env.NODE_ENV !== 'development' }),
+]
+```

package/docs/lib/pinch.md

@@ -0,0 +1,98 @@
+# createPinchListener
+
+Attaches a two-finger pinch gesture listener to `window`. Tracks cumulative scale across gestures, snapping to `1` when crossing the natural scale boundary. Fires a callback on every move tick where the finger distance changes.
+
+## Usage
+
+```ts
+import { createPinchListener } from '@inizioevoke/astro-core/lib/gestures';
+
+const pinch = createPinchListener((scale, gesture) => {
+  console.log(gesture, scale); // 'spread' 1.23
+});
+
+// Later, to clean up:
+pinch.dispose();
+```
+
+## API
+
+### `createPinchListener(onPinch)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `onPinch` | `(scale: number, gesture: PinchGesture) => void` | Called each time the pinch distance changes. Receives the current cumulative scale and the gesture direction. |
+
+**Returns** a `PinchController`.
+
+### `PinchController`
+
+| Method | Description |
+|--------|-------------|
+| `enable()` | Attaches listeners and begins tracking. Called automatically on creation. |
+| `disable()` | Removes all listeners and resets internal state. Can be re-enabled with `enable()`. |
+| `dispose()` | Alias for `disable()`. Use when tearing down permanently. |
+
+### `PinchGesture`
+
+```ts
+type PinchGesture = 'spread' | 'pinch'
+```
+
+| Value | Description |
+|-------|-------------|
+| `'spread'` | Fingers moving apart |
+| `'pinch'` | Fingers moving together |
+
+## Behavior
+
+- Requires exactly two simultaneous touch points — single-finger touches are ignored.
+- Scale is **cumulative**: each new gesture continues from where the previous one ended.
+- Snaps to `1` when the scale crosses the natural boundary (e.g. transitioning from `1.2` to `0.9` in a single gesture yields `1` instead of `0.9`).
+- All `touchmove` and `touchend` listeners are added passively and cleaned up automatically when the gesture ends.
+
+## Examples
+
+### Zoom an element
+
+```ts
+import { createPinchListener } from '@inizioevoke/astro-core';
+
+const image = document.querySelector('#zoomable') as HTMLElement;
+
+const pinch = createPinchListener((scale) => {
+  image.style.transform = `scale(${scale})`;
+});
+```
+
+### React to gesture direction
+
+```ts
+import { createPinchListener, type PinchGesture } from '@inizioevoke/astro-core';
+
+const pinch = createPinchListener((scale, gesture) => {
+  if (gesture === 'spread') {
+    // fingers apart — zooming in
+  } else {
+    // fingers together — zooming out
+  }
+});
+```
+
+### Temporarily pause and resume
+
+```ts
+const pinch = createPinchListener((scale, gesture) => { /* ... */ });
+
+pinch.disable(); // pause
+pinch.enable();  // resume
+```
+
+### Clean up on component teardown
+
+```ts
+const pinch = createPinchListener((scale, gesture) => { /* ... */ });
+
+// Astro / vanilla teardown
+document.addEventListener('astro:before-swap', () => pinch.dispose(), { once: true });
+```

package/docs/lib/swipe.md

@@ -0,0 +1,147 @@
+# createSwipeListener
+
+Attaches a touch swipe gesture listener to `window`. Detects directional swipes based on a configurable distance threshold and fires a callback when the gesture completes.
+
+## Usage
+
+```ts
+import { createSwipeListener } from '@inizioevoke/astro-core/lib/gestures';
+
+const swipe = createSwipeListener('left-right', '1/3', ({ direction, distance, duration }) => {
+  console.log(direction, distance.x, duration); // 'left' -180 320
+});
+
+// Later, to disable without removing:
+swipe.disable();
+
+// Re-enable:
+swipe.enable();
+
+// Fully clean up:
+swipe.dispose();
+```
+
+## API
+
+### `createSwipeListener(direction, threshold, handler)`
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `direction` | `SwipeDirection` | Which swipe direction(s) to listen for. |
+| `threshold` | `SwipeThreshold` | Minimum swipe distance required to trigger the handler. A fractional string is relative to the screen dimension of the primary axis. |
+| `handler` | `OnSwipeHandler` | Called when a qualifying swipe completes. |
+
+**Returns** a `SwipeController` — `{ enable, disable, dispose }` — for managing the listener lifecycle.
+
+The listener is **enabled automatically** on creation. `dispose` is an alias for `disable`.
+
+### `SwipeDirection`
+
+```ts
+type SwipeDirection = 'left' | 'right' | 'left-right' | 'up' | 'down' | 'up-down';
+```
+
+| Value | Description |
+|-------|-------------|
+| `'left'` | Rightward-to-leftward horizontal swipe |
+| `'right'` | Leftward-to-rightward horizontal swipe |
+| `'left-right'` | Either horizontal direction |
+| `'up'` | Bottom-to-top vertical swipe |
+| `'down'` | Top-to-bottom vertical swipe |
+| `'up-down'` | Either vertical direction |
+
+### `SwipeThreshold`
+
+```ts
+type SwipeThreshold = '1/4' | '1/3' | '1/2' | number;
+```
+
+Fractional strings are converted to a pixel distance at creation time based on the primary axis:
+
+- Horizontal swipes (`left`, `right`, `left-right`) use `window.innerWidth`
+- Vertical swipes (`up`, `down`, `up-down`) use `window.innerHeight`
+
+Pass a `number` to specify an exact pixel distance.
+
+### `OnSwipeHandlerArgs`
+
+```ts
+interface OnSwipeHandlerArgs {
+  direction: SwipeDirection;
+  threshold: number;
+  distance: { x: number; y: number };
+  duration: number;
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `direction` | The resolved direction of the swipe (`'left'`, `'right'`, `'up'`, or `'down'`). |
+| `threshold` | The resolved pixel threshold used for this listener. |
+| `distance.x` | Horizontal delta in pixels (positive = leftward, negative = rightward). |
+| `distance.y` | Vertical delta in pixels (positive = upward, negative = downward). |
+| `duration` | Time in milliseconds from `touchstart` to `touchend`. |
+
+### `SwipeController`
+
+```ts
+interface SwipeController {
+  enable: () => void;
+  disable: () => void;
+  dispose: () => void;
+}
+```
+
+| Method | Description |
+|--------|-------------|
+| `enable()` | Attaches touch event listeners. No-op if already enabled. |
+| `disable()` | Detaches touch event listeners. The controller can be re-enabled. |
+| `dispose()` | Alias for `disable()`. |
+
+## Behavior
+
+- Only single-finger swipes are recognized — multi-touch contacts cancel the active gesture.
+- A swipe is only fired if the gesture is primarily along the primary axis. Off-axis drift must stay below the threshold or the swipe is ignored.
+- The threshold pixel value is computed once at creation — it does not update on orientation change or resize.
+- All touch listeners are added passively.
+
+## Examples
+
+### Navigate a carousel on horizontal swipe
+
+```ts
+import { createSwipeListener } from '@inizioevoke/astro-core';
+
+const swipe = createSwipeListener('left-right', '1/3', ({ direction }) => {
+  if (direction === 'left') carousel.next();
+  else carousel.prev();
+});
+```
+
+### Dismiss a sheet on downward swipe
+
+```ts
+import { createSwipeListener } from '@inizioevoke/astro-core';
+
+const swipe = createSwipeListener('down', '1/4', () => {
+  sheet.close();
+});
+```
+
+### Pause detection while a modal is open
+
+```ts
+const swipe = createSwipeListener('left-right', '1/3', handler);
+
+modal.addEventListener('open', () => swipe.disable());
+modal.addEventListener('close', () => swipe.enable());
+```
+
+### Clean up on component teardown
+
+```ts
+const swipe = createSwipeListener('up', '1/3', handler);
+
+// Astro / vanilla teardown
+document.addEventListener('astro:before-swap', swipe.dispose, { once: true });
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inizioevoke/astro-core",
-  "version": "2.1.2",
+  "version": "2.2.1",
   "description": "",
   "license": "ISC",
   "author": "",
@@ -18,6 +18,7 @@
     "./lib/gestures": "./src/lib/gestures/index.ts"
   },
   "files": [
+    "docs",
     "src",
     "index.ts"
   ],

package/src/components/CssBackgroundImage.astro

@@ -0,0 +1,103 @@
+---
+// See /docs/components/CssBackgroundImage.md
+import type { ImageMetadata, ImageOutputFormat } from "astro";
+import { getImage } from "astro:assets";
+
+type ImageSize = 'contain' | 'cover';
+type ImagePosition = 'left top' | 'left center' | 'left bottom' | 'center top' | 'center center' | 'center bottom' | 'right top' | 'right center' | 'right bottom';
+
+interface ImageSrcProps {
+  image: ImageMetadata;
+  optimize?: boolean;
+  format?: ImageOutputFormat;
+  quality?: number;
+  width?: number;
+  height?: number;
+}
+interface BgImageProps extends ImageSrcProps {
+  size?: ImageSize | (string & {});
+  position?: ImagePosition | (string & {});
+  repeat?: 'no-repeat' | 'repeat-x' | 'repeat-y' | 'repeat';
+  important?: true;
+}
+export interface Props extends BgImageProps {
+  selector?: string;
+  
+  breakpoints?: ({
+    minWidth?: string | number;
+    maxWidth?: string | number;
+  } & BgImageProps)[];
+}
+
+const { 
+  selector, 
+  image,
+  optimize = true,
+  format,
+  quality, 
+  width,
+  height,
+  size, 
+  position, 
+  repeat, 
+  important, 
+  breakpoints = [] 
+} = Astro.props;
+
+const styles: string[] = [];
+
+async function getImageSrc({image, format, quality, width, height, optimize}: ImageSrcProps) {
+  if (optimize !== false) {
+    const img = await getImage({
+      src: image,
+      format: format ?? image.format,
+      quality: quality,
+      width,
+      height
+    });
+    return img.src;
+  } else {
+    return image.src;
+  }
+}
+
+if (image) {
+  const src = await getImageSrc({ image, format, quality, width, height, optimize });
+  styles.push(`background-image:url("${src}")${important ? '!important' : ''};`);
+}
+
+size && styles.push(`background-size:${size}${important ? '!important' : ''};`);
+position && styles.push(`background-position:${position}${important ? '!important' : ''};`);
+repeat && styles.push(`background-repeat:${repeat}${important ? '!important' : ''};`);
+
+for (const bp of breakpoints) {
+  const widths = [];
+  if (bp.minWidth) {
+    widths.push(`(min-width:${typeof bp.minWidth == 'number' ? `${bp.minWidth}px` : bp.minWidth})`);
+  }
+  if (bp.maxWidth) {
+    widths.push(`(max-width:${typeof bp.maxWidth == 'number' ? `${bp.maxWidth}px` : bp.maxWidth})`);
+  }
+  if (widths.length > 0) {
+    // const bpImg = await getImage({ src: bp.image });
+    styles.push(`@media screen and ${widths.join(' and ')}{`);
+    if (bp.image) {
+      const src = await getImageSrc(bp);
+      styles.push(`background-image:url("${src}")${important ? '!important' : ''};`);
+    }
+    bp.size && styles.push(`background-size:${bp.size}${important ? '!important' : ''};`);
+    bp.position && styles.push(`background-position:${bp.position}${important ? '!important' : ''};`);
+    bp.repeat && styles.push(`background-repeat:${bp.repeat}${important ? '!important' : ''};`);
+    styles.push('}');
+  }
+}
+
+const html = [`${import.meta.env.PROD ? '' : '\n'}${selector ?? 'body'}{`]
+  .concat(styles.map((s) => { 
+    return `${s}`; 
+  }))
+  .concat(['}'])
+  .join(import.meta.env.PROD ? '' : '\n');
+---
+
+<style set:html={html} />