spaper 1.4.0 → 2.0.0

package/README.md

@@ -1,7 +1,8 @@
 ![version](https://img.shields.io/npm/v/spaper)
 
 # Spaper
-PaperCSS components for Svelte
+
+PapierCSS components for Svelte
 
 ## Documentation
 
@@ -9,98 +10,59 @@ Browse [documentation and demo here](https://oli8.github.io/spaper/).
 
 ## Start
 
-### Import papercss
-
-Add a link to the CDN into your HTML file:  
-
-```html
-<link rel="stylesheet" href="https://unpkg.com/papercss/dist/paper.min.css">
-```
-
-Or use NPM:
+### Install
 
 ```bash
-npm i papercss
-```  
-
-then import in your main component:
-```html
-<script>
-  import 'papercss/dist/paper.min.css'
-</script>
+npm i spaper papiercss tailwindcss
 ```
 
-### Install spaper
+### Import papiercss
 
-```bash
-npm i spaper
+```css
+@import 'papiercss/fonts.css'; /* optional */
+@import 'tailwindcss';
+@import 'papiercss';
+@source '../node_modules/spaper';
 ```
 
+`@source` is relative to the CSS file. This scans the installed package so Tailwind generates the utility classes used inside the components.
+
 ### Usage
 
 ```html
 <script>
-  import { Button } from 'spaper';
-  // or
-  import Alert from 'spaper/components/Alert.Svelte';
+  import { Button } from 'spaper'
 </script>
 
-<Alert>...</Alert>
-<Button>Click me</Button>
+<button>Click me</button>
 ```
 
 <hr />
 
-### Sponsors
-
-Thanks to these generous people! :heart:
-
-<table>
-  <tr>
-    <td align="center">
-      <a href="https://github.com/mehdi-dalil">
-        <img src="https://avatars.githubusercontent.com/u/65339771?v=4" width="80px;" alt=""/><br />
-        <sub><b>mehdi-dalil</b></sub>
-      </a>
-    </td>
-    <td align="center">
-      <a href="https://github.com/t0kido">
-        <img src="https://avatars.githubusercontent.com/u/12486500?v=4" width="80px;" alt=""/><br />
-        <sub><b>t0kido</b></sub>
-      </a>
-    </td>
-  </tr>
-</table>
-
-
 ### Donate
 
 Any donation is greatly appreciated :heart:
 
-| Source          | Link / Address                             |
-| :-------------- | :------------------------------------------|
-| Github Sponsor  | https://github.com/sponsors/Oli8           |
-| PayPal          | https://paypal.me/OliCrt                   |
-| Bitcoin         | 1Ez3Ts2WShUcbeGCjhZapdxVDK77DbYjdU         |
-| Ethereum        | 0xc4364cafac87fd8085dc26af4a4a8c3bbad1bd3e |
+| Source         | Link / Address                   |
+| :------------- | :------------------------------- |
+| Github Sponsor | https://github.com/sponsors/Oli8 |
+| PayPal         | https://paypal.me/OliCrt         |
 
 #### Components
 
 - Alert
 - Article
-- Badge
+- Tag
 - Breadcrumb
 - Button
 - Card
 - Carousel
 - CloseButton
-- Col
 - Collapsible
 - CopyButton
-- Form
 - Checkbox
 - Input
-- NuberInput
+- NumberInput
 - Radio
 - Select
 - Slider
@@ -111,7 +73,6 @@ Any donation is greatly appreciated :heart:
 - Pagination
 - Popover
 - Progress
-- Row
 - Skeleton
 - Table
 - Tabs

package/dist/components/Alert.svelte

@@ -0,0 +1,83 @@
+<script lang="ts">
+import { fade, slide } from 'svelte/transition'
+import type { SlideParams, TransitionConfig } from 'svelte/transition'
+import type { PaperType } from '../types'
+import type { IconNode } from '../icons'
+import { typeIcons } from '../type-icons'
+import CloseButton from './CloseButton.svelte'
+import Icon from './Icon.svelte'
+
+/** outro: collapse from `slide`, opacity from `fade`. */
+function slideFade(node: Element, params: SlideParams = {}): TransitionConfig {
+  const slideTrans = slide(node, params)
+  const fadeTrans = fade(node, params)
+  return {
+    delay: slideTrans.delay,
+    duration: slideTrans.duration,
+    easing: slideTrans.easing,
+    css: (t, u) =>
+      [slideTrans.css?.(t, u), fadeTrans.css?.(t, u)].filter(Boolean).join(';'),
+  }
+}
+
+interface Props {
+  type?: PaperType
+  /** Replaces the icon chosen from `type`. */
+  icon?: IconNode | null
+  /** Hides the icon, including the one chosen from `type`. */
+  hideIcon?: boolean
+  dismissible?: boolean
+  children?: import('svelte').Snippet
+  [key: string]: any
+}
+
+let {
+  type = 'primary',
+  icon = null,
+  hideIcon = false,
+  dismissible = false,
+  children,
+  ...rest
+}: Props = $props()
+
+const typeClass: Record<PaperType, string> = {
+  primary: 'alert-paper-primary',
+  secondary: 'alert-paper-secondary',
+  success: 'alert-paper-success',
+  warning: 'alert-paper-warning',
+  danger: 'alert-paper-danger',
+}
+
+let shownIcon = $derived(hideIcon ? null : (icon ?? typeIcons[type]))
+let closed: boolean = $state(false)
+
+function close(): void {
+  closed = true
+}
+</script>
+
+{#if !closed}
+  <div
+    {...rest}
+    class={[
+      'alert-paper',
+      { 'alert-paper-dismissible': dismissible },
+      typeClass[type],
+      rest.class,
+    ]}
+    role="alert"
+    out:slideFade={{ duration: 500 }}
+  >
+    <div class="flex items-center gap-2">
+      {#if shownIcon}
+        <Icon name={shownIcon} size={22} class="shrink-0" />
+      {/if}
+      <div>
+        {@render children?.()}
+      </div>
+    </div>
+    {#if dismissible}
+      <CloseButton onclick={close} />
+    {/if}
+  </div>
+{/if}

package/dist/components/Alert.svelte.d.ts

@@ -0,0 +1,15 @@
+import type { PaperType } from '../types';
+import type { IconNode } from '../icons';
+interface Props {
+    type?: PaperType;
+    /** Replaces the icon chosen from `type`. */
+    icon?: IconNode | null;
+    /** Hides the icon, including the one chosen from `type`. */
+    hideIcon?: boolean;
+    dismissible?: boolean;
+    children?: import('svelte').Snippet;
+    [key: string]: any;
+}
+declare const Alert: import("svelte").Component<Props, {}, "">;
+type Alert = ReturnType<typeof Alert>;
+export default Alert;

package/dist/components/Article.svelte

@@ -0,0 +1,63 @@
+<script lang="ts">
+import type { Snippet } from 'svelte'
+import type { HeadingLevel, StringOrSnippet } from '../types'
+import { isSnippet } from '../utils'
+
+interface Props {
+  title?: StringOrSnippet
+  /** Heading element for the title. */
+  titleAs?: HeadingLevel
+  meta?: StringOrSnippet
+  textLead?: StringOrSnippet
+  border?: boolean
+  children?: Snippet
+  footer?: Snippet
+  class?: string
+  [key: string]: unknown
+}
+
+let {
+  title = '',
+  titleAs = 'h3',
+  meta = '',
+  textLead = '',
+  border = false,
+  children,
+  footer,
+  class: className = '',
+  ...rest
+}: Props = $props()
+</script>
+
+<article
+  {...rest}
+  class={['article-paper', { 'border-paper': border }, className]}
+>
+  {#if isSnippet(title) || title}
+    <svelte:element this={titleAs} class="article-paper-title">
+      {#if isSnippet(title)}{@render title()}{:else}{title}{/if}
+    </svelte:element>
+  {/if}
+
+  {#if isSnippet(meta) || meta}
+    <p class="article-paper-meta">
+      {#if isSnippet(meta)}{@render meta()}{:else}{meta}{/if}
+    </p>
+  {/if}
+
+  {#if isSnippet(textLead) || textLead}
+    <p class="article-paper-lead">
+      {#if isSnippet(textLead)}{@render textLead()}{:else}{textLead}{/if}
+    </p>
+  {/if}
+
+  {#if children}
+    <p>{@render children()}</p>
+  {/if}
+
+  {#if footer}
+    <footer class="flex flex-wrap">
+      {@render footer()}
+    </footer>
+  {/if}
+</article>

package/dist/components/Article.svelte.d.ts

@@ -0,0 +1,17 @@
+import type { Snippet } from 'svelte';
+import type { HeadingLevel, StringOrSnippet } from '../types';
+interface Props {
+    title?: StringOrSnippet;
+    /** Heading element for the title. */
+    titleAs?: HeadingLevel;
+    meta?: StringOrSnippet;
+    textLead?: StringOrSnippet;
+    border?: boolean;
+    children?: Snippet;
+    footer?: Snippet;
+    class?: string;
+    [key: string]: unknown;
+}
+declare const Article: import("svelte").Component<Props, {}, "">;
+type Article = ReturnType<typeof Article>;
+export default Article;

package/dist/components/Avatar/Avatar.svelte

@@ -0,0 +1,102 @@
+<script lang="ts">
+import type { PaperSize, PaperColor } from '../../types'
+
+const NAMED_SIZES = new Set<PaperSize>(['small', 'default', 'large'])
+
+interface Props {
+  src?: string | null | undefined
+  label?: string
+  title?: string
+  type?: PaperColor
+  /** Size of the avatar. PapierCSS size or any CSS length. */
+  size?: PaperSize | string
+  /** Imperfect circle variant (`avatar-paper-circle-1` … `6`). */
+  circle?: number
+  children?: import('svelte').Snippet
+  [key: string]: any
+}
+
+let {
+  src = undefined,
+  label = '',
+  title = '',
+  type = 'primary',
+  size = 'default',
+  circle = 1,
+  children,
+  ...rest
+}: Props = $props()
+
+let failed = $state(false)
+let previousSrc: string | null | undefined
+
+$effect.pre(() => {
+  if (src === previousSrc) return
+  previousSrc = src
+  failed = false
+})
+
+let titleAttr = $derived(title || label)
+let fallbackText = $derived(label.slice(0, 2))
+
+const sizeClass: Record<PaperSize, string> = {
+  small: 'avatar-paper-sm',
+  default: '',
+  large: 'avatar-paper-lg',
+}
+
+const typeClass: Record<PaperColor, string> = {
+  primary: 'avatar-paper-primary',
+  secondary: 'avatar-paper-secondary',
+  success: 'avatar-paper-success',
+  warning: 'avatar-paper-warning',
+  danger: 'avatar-paper-danger',
+  muted: 'avatar-paper-muted',
+}
+
+let isNamedSize = $derived(
+  typeof size === 'string' && NAMED_SIZES.has(size as PaperSize),
+)
+let resolvedSizeClass = $derived(
+  isNamedSize ? sizeClass[size as PaperSize] : '',
+)
+let customSizeStyle = $derived(
+  !isNamedSize && size
+    ? `--paper-avatar-size: ${size}; --paper-avatar-font-size: calc(${size} * 0.45);`
+    : '',
+)
+const circleClasses = [
+  'avatar-paper-circle-1',
+  'avatar-paper-circle-2',
+  'avatar-paper-circle-3',
+  'avatar-paper-circle-4',
+  'avatar-paper-circle-5',
+  'avatar-paper-circle-6',
+]
+let circleClass = $derived(circleClasses[((circle || 1) - 1) % 6])
+</script>
+
+<span
+  {...rest}
+  class={[
+    'avatar-paper',
+    typeClass[type],
+    circleClass,
+    resolvedSizeClass,
+    rest.class,
+  ]}
+  style={customSizeStyle}
+  title={titleAttr}
+  aria-label={label || undefined}
+>
+  {#if src && !failed}
+    <img
+      {src}
+      alt={label}
+      referrerpolicy="no-referrer"
+      onerror={() => (failed = true)}
+    />
+  {:else}
+    {#if children}{@render children()}{:else}{fallbackText}{/if}
+  {/if}
+</span>

package/dist/components/Avatar/Avatar.svelte.d.ts

@@ -0,0 +1,16 @@
+import type { PaperSize, PaperColor } from '../../types';
+interface Props {
+    src?: string | null | undefined;
+    label?: string;
+    title?: string;
+    type?: PaperColor;
+    /** Size of the avatar. PapierCSS size or any CSS length. */
+    size?: PaperSize | string;
+    /** Imperfect circle variant (`avatar-paper-circle-1` … `6`). */
+    circle?: number;
+    children?: import('svelte').Snippet;
+    [key: string]: any;
+}
+declare const Avatar: import("svelte").Component<Props, {}, "">;
+type Avatar = ReturnType<typeof Avatar>;
+export default Avatar;

package/dist/components/Avatar/AvatarGroup.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+import type { PaperSize } from '../../types'
+
+interface Props {
+  size?: PaperSize
+  children?: import('svelte').Snippet
+  [key: string]: any
+}
+
+let { size = 'default', children, ...rest }: Props = $props()
+
+const sizeClass: Record<PaperSize, string> = {
+  small: 'avatar-paper-stack-sm',
+  default: '',
+  large: 'avatar-paper-stack-lg',
+}
+</script>
+
+<div {...rest} class={['avatar-paper-stack', sizeClass[size], rest.class]}>
+  {@render children?.()}
+</div>

package/dist/components/Avatar/AvatarGroup.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { PaperSize } from '../../types';
+interface Props {
+    size?: PaperSize;
+    children?: import('svelte').Snippet;
+    [key: string]: any;
+}
+declare const AvatarGroup: import("svelte").Component<Props, {}, "">;
+type AvatarGroup = ReturnType<typeof AvatarGroup>;
+export default AvatarGroup;

package/dist/components/Avatar/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Avatar } from './Avatar.svelte';
+export { default as AvatarGroup } from './AvatarGroup.svelte';

package/dist/components/Avatar/index.js

@@ -0,0 +1,2 @@
+export { default as Avatar } from './Avatar.svelte';
+export { default as AvatarGroup } from './AvatarGroup.svelte';

package/dist/components/Breadcrumb.svelte

@@ -0,0 +1,33 @@
+<script lang="ts">
+interface Props {
+  border?: boolean
+  items?: { text: string; href?: string }[]
+  ariaLabel?: string
+  [key: string]: any
+}
+
+let {
+  border = false,
+  items = [],
+  ariaLabel = 'Breadcrumb',
+  ...rest
+}: Props = $props()
+</script>
+
+<nav
+  {...rest}
+  class={['breadcrumb-paper', { 'border-paper': border }, rest.class]}
+  aria-label={ariaLabel}
+>
+  <ol>
+    {#each items as { text, href }}
+      <li>
+        {#if href}
+          <a {href}>{text}</a>
+        {:else}
+          {text}
+        {/if}
+      </li>
+    {/each}
+  </ol>
+</nav>

package/dist/components/Breadcrumb.svelte.d.ts

@@ -0,0 +1,12 @@
+interface Props {
+    border?: boolean;
+    items?: {
+        text: string;
+        href?: string;
+    }[];
+    ariaLabel?: string;
+    [key: string]: any;
+}
+declare const Breadcrumb: import("svelte").Component<Props, {}, "">;
+type Breadcrumb = ReturnType<typeof Breadcrumb>;
+export default Breadcrumb;

package/dist/components/Button.svelte

@@ -0,0 +1,174 @@
+<script lang="ts">
+import type { Attributes, PaperSize, PaperType } from '../types'
+import type { IconNode } from '../icons'
+import { getDomAttributes } from '../utils'
+import Icon from './Icon.svelte'
+import Spinner from './Spinner.svelte'
+
+interface Props {
+  type?: PaperType | null
+  /** Icon shown to the left of the label. */
+  icon?: IconNode | null
+  size?: PaperSize
+  block?: boolean
+  disabled?: boolean
+  loading?: boolean
+  outline?: PaperType | null
+  /**
+   * The `type` attribute for `<button>`. Useful for forms.
+   * Ignored if rendered as a link.
+   */
+  nativeType?: 'submit' | 'reset' | 'button' | null
+  /** When true, the button is rendered as an `<a>` element. */
+  isLink?: boolean
+  href?: string | null
+  /** When true and `isLink` is set,
+   * adds `target="_blank"` and `rel="noopener noreferrer"`
+   * to the link for external navigation.
+   */
+  external?: boolean
+  onclick?: (e: MouseEvent) => void
+  children?: import('svelte').Snippet
+  /** Replaces the default spinner while `loading` is set. */
+  loader?: import('svelte').Snippet
+  [key: string]: any
+}
+
+let {
+  type = null,
+  icon = null,
+  size = 'default',
+  block = false,
+  disabled = false,
+  loading = false,
+  outline = null,
+  nativeType = null,
+  isLink = false,
+  href = null,
+  external = false,
+  onclick,
+  children,
+  loader,
+  ...rest
+}: Props = $props()
+
+const sizeClass: Record<PaperSize, string> = {
+  small: 'btn-paper-sm',
+  default: '',
+  large: 'btn-paper-lg',
+}
+
+const iconSize: Record<PaperSize, number> = {
+  small: 16,
+  default: 18,
+  large: 28,
+}
+
+const typeClass: Record<PaperType, string> = {
+  primary: 'btn-paper-primary',
+  secondary: 'btn-paper-secondary',
+  success: 'btn-paper-success',
+  warning: 'btn-paper-warning',
+  danger: 'btn-paper-danger',
+}
+
+const outlineClass: Record<PaperType, string> = {
+  primary: 'btn-paper-primary-outline',
+  secondary: 'btn-paper-secondary-outline',
+  success: 'btn-paper-success-outline',
+  warning: 'btn-paper-warning-outline',
+  danger: 'btn-paper-danger-outline',
+}
+
+const inactive = $derived(disabled || loading)
+const spinnerType = $derived(outline ?? type ?? 'secondary')
+const classes = $derived([
+  'btn-paper',
+  sizeClass[size],
+  { 'btn-paper-block': block },
+  type && typeClass[type],
+  outline && outlineClass[outline],
+  { disabled: inactive },
+  rest.class,
+])
+const attr: Attributes = $derived(
+  getDomAttributes({
+    props: rest,
+    classes: '',
+    toOmit: ['class'],
+  }),
+)
+
+function handleClick(e: MouseEvent) {
+  if (inactive) e.preventDefault()
+  onclick?.(e)
+}
+
+function linkRel(rel: unknown) {
+  const tokens = new Set(
+    (typeof rel === 'string' ? rel : '').split(/\s+/).filter(Boolean),
+  )
+  tokens.add('noopener')
+  tokens.add('noreferrer')
+  return [...tokens].join(' ')
+}
+
+const anchorRel = $derived(
+  external
+    ? linkRel(attr.rel)
+    : typeof attr.rel === 'string'
+      ? attr.rel
+      : undefined,
+)
+</script>
+
+{#snippet content()}
+  {#if loading || icon}
+    <span class="inline-flex items-center gap-2 align-middle">
+      {#if loading}
+        {#if loader}
+          {@render loader()}
+        {:else}
+          <Spinner
+            type={spinnerType}
+            size="small"
+            inline
+            ariaLabel=""
+            aria-hidden="true"
+          />
+        {/if}
+      {/if}
+      {#if icon}
+        <Icon name={icon} size={iconSize[size]} class="shrink-0" />
+      {/if}
+      {@render children?.()}
+    </span>
+  {:else}
+    {@render children?.()}
+  {/if}
+{/snippet}
+
+{#if isLink || href}
+  <a
+    href={href ?? undefined}
+    target={external ? '_blank' : undefined}
+    aria-busy={loading || undefined}
+    {...attr}
+    class={classes}
+    rel={anchorRel}
+    onclick={handleClick}
+  >
+    {@render content()}
+  </a>
+{:else}
+  <button
+    {...attr}
+    class={classes}
+    type={nativeType}
+    disabled={inactive}
+    aria-busy={loading || undefined}
+    onclick={handleClick}
+  >
+    {@render content()}
+  </button>
+{/if}