# Pinned List

List where any row can be pinned. Pinned rows glide into a Pinned group at the top with a FLIP animation and glide back when unpinned.

- Category: MarkasUI
- Status: stable
- Registry: https://markas.jenderalcorp.com/r/pinned-list.json
- CLI: `npx markasui@latest add pinned-list`

## When to use

Lists where people keep a few favorites at the top, such as channels, saved searches, documents, or cities.

- Give every item a stable value
- Keep items in their natural order, the component sorts pinned rows itself
- Store the pinned list from onPinnedChange so it survives reloads
- Keep meta short, such as a time or a count

## Code

### Blade

Save at `resources/views/components/markas/pinned-list.blade.php`. Dependencies: alpinejs.

```blade
@props([
    'items' => [],
    'defaultPinned' => [],
    'pinLabel' => 'Pin {label}',
    'unpinLabel' => 'Unpin {label}',
    'pinnedLabel' => 'Pinned',
    'allLabel' => 'All',
    'pinnedMessage' => '{label} pinned',
    'unpinnedMessage' => '{label} unpinned',
])

@php
    $root = 'grid gap-5';
    $group = 'grid gap-2';
    $heading = 'flex items-center gap-2 px-1 text-xs font-medium text-muted transition-opacity duration-300 ease-out starting:opacity-0 motion-reduce:transition-none';
    $count = 'rounded-full bg-subtle px-1.5 text-[11px] leading-4 text-muted tabular-nums';
    $list = 'grid gap-1.5';
    $itemClass = 'relative flex items-center gap-3 rounded-xl border border-line bg-surface px-3 py-2.5 transition-colors duration-300 ease-out data-[pinned=true]:border-primary-line data-[pinned=true]:bg-primary-soft motion-reduce:transition-none';
    $iconTile = 'grid size-9 shrink-0 place-items-center rounded-lg bg-subtle text-ink transition-colors duration-300 ease-out in-data-[pinned=true]:bg-surface motion-reduce:transition-none';
    $iconClass = 'size-5';
    $body = 'grid min-w-0 flex-1';
    $labelClass = 'truncate text-sm font-medium text-ink';
    $descriptionClass = 'truncate text-xs text-muted';
    $metaClass = 'shrink-0 text-xs text-muted tabular-nums';
    $pinButton = 'group/pin grid size-8 shrink-0 place-items-center rounded-lg text-muted transition-colors duration-150 ease-out hover:bg-subtle hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary aria-pressed:text-ink motion-reduce:transition-none';
    $pinIcon = 'size-4 rotate-45 transition-transform duration-300 ease-[cubic-bezier(0.34,1.56,0.64,1)] group-aria-pressed/pin:rotate-0 group-aria-pressed/pin:fill-current motion-reduce:transition-none';
    $srOnly = 'sr-only';

    $pinPath = 'M12 17v5M9 10.8a2 2 0 0 1-1.1 1.8l-1.8.9A2 2 0 0 0 5 15.2v.8a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.8a2 2 0 0 0-1.1-1.8l-1.8-.9a2 2 0 0 1-1.1-1.8V7a1 1 0 0 1 1-1 2 2 0 0 0 0-4H8a2 2 0 0 0 0 4 1 1 0 0 1 1 1z';
    $items = array_map(fn ($item) => [
        'value' => (string) $item['value'],
        'label' => $item['label'],
        'description' => $item['description'] ?? null,
        'meta' => $item['meta'] ?? null,
        'icon' => $item['icon'] ?? null,
    ], array_values($items));
    $defaultPinned = array_map('strval', array_values($defaultPinned));
    $svg = 'viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"';
@endphp

{{-- Pinning moves a row into the Pinned group with a FLIP animation and dispatches a change event with the pinned values. --}}
<div
    x-data="{
        items: @js($items),
        pinned: @js($defaultPinned),
        message: '',
        labels: @js(['pin' => $pinLabel, 'unpin' => $unpinLabel, 'pinned' => $pinnedMessage, 'unpinned' => $unpinnedMessage]),
        {{-- Length and curve of the move between groups. --}}
        duration: 350,
        easing: 'cubic-bezier(0.2, 0.8, 0.2, 1)',
        get groups() {
            return [
                { label: @js($pinnedLabel), items: this.items.filter((item) => this.pinned.includes(item.value)) },
                { label: @js($allLabel), items: this.items.filter((item) => !this.pinned.includes(item.value)) },
            ];
        },
        label(key, item) {
            return this.labels[key].replace('{label}', item.label);
        },
        rows(host) {
            return Array.from(host.querySelectorAll('[data-value]'));
        },
        toggle(item) {
            const host = this.$el.closest('[data-pinned-list]');
            const on = !this.pinned.includes(item.value);
            const before = new Map(this.rows(host).map((row) => [row.dataset.value, row.getBoundingClientRect()]));
            this.pinned = on ? [...this.pinned, item.value] : this.pinned.filter((value) => value !== item.value);
            this.message = this.label(on ? 'pinned' : 'unpinned', item);
            this.$dispatch('change', this.pinned);
            this.$nextTick(() => this.flip(host, before, item.value));
        },
        {{-- FLIP: start each row where it was and let it glide to its new place, then refocus the moved pin button. --}}
        flip(host, before, moved) {
            const still = matchMedia('(prefers-reduced-motion: reduce)').matches;
            for (const row of this.rows(host)) {
                if (row.dataset.value === moved) row.querySelector('button')?.focus();
                const old = before.get(row.dataset.value);
                const now = row.getBoundingClientRect();
                if (still || !old) continue;
                const [x, y] = [old.left - now.left, old.top - now.top];
                if (!x && !y) continue;
                const zIndex = row.dataset.value === moved ? 1 : 0;
                row.animate([{ transform: `translate(${x}px, ${y}px)`, zIndex }, { transform: 'none', zIndex }], { duration: this.duration, easing: this.easing });
            }
        },
    }"
    data-pinned-list
    {{ $attributes->class([$root]) }}
>
    <template x-for="(part, index) in groups" :key="index">
        <div x-bind:hidden="!part.items.length" class="{{ $group }}">
            <p class="{{ $heading }}"><span x-text="part.label"></span><span class="{{ $count }}" x-text="part.items.length"></span></p>
            <ul x-bind:aria-label="part.label" class="{{ $list }}">
                <template x-for="item in part.items" :key="item.value">
                    <li x-bind:data-value="item.value" x-bind:data-pinned="pinned.includes(item.value)" class="{{ $itemClass }}">
                        <template x-if="item.icon">
                            <span aria-hidden="true" class="{{ $iconTile }}"><svg class="{{ $iconClass }}" {!! $svg !!}><path x-bind:d="item.icon" /></svg></span>
                        </template>
                        <span class="{{ $body }}">
                            <span class="{{ $labelClass }}" x-text="item.label"></span>
                            <template x-if="item.description">
                                <span class="{{ $descriptionClass }}" x-text="item.description"></span>
                            </template>
                        </span>
                        <template x-if="item.meta">
                            <span class="{{ $metaClass }}" x-text="item.meta"></span>
                        </template>
                        <button
                            type="button"
                            x-bind:aria-pressed="pinned.includes(item.value) ? 'true' : 'false'"
                            x-bind:aria-label="label('pin', item)"
                            x-bind:title="label(pinned.includes(item.value) ? 'unpin' : 'pin', item)"
                            x-on:click="toggle(item)"
                            class="{{ $pinButton }}"
                        >
                            <svg class="{{ $pinIcon }}" {!! $svg !!} aria-hidden="true"><path d="{{ $pinPath }}" /></svg>
                        </button>
                    </li>
                </template>
            </ul>
        </div>
    </template>
    <p role="status" class="{{ $srOnly }}" x-text="message"></p>
</div>
```

```blade
<x-markas.pinned-list
    :default-pinned="$user->pinned_channels"
    x-on:change="fetch('/pins', { method: 'PUT', body: JSON.stringify($event.detail) })"
    :items="[
        ['value' => 'general', 'label' => 'general', 'description' => 'Company-wide announcements', 'meta' => '128'],
        ['value' => 'design', 'label' => 'design-crit', 'description' => 'Weekly critiques', 'meta' => '14'],
        ['value' => 'random', 'label' => 'random', 'meta' => '9'],
    ]"
/>
```

### React

Save at `src/components/markas/PinnedList.tsx`. No extra dependencies.

```tsx
"use client";

import { useLayoutEffect, useRef, useState, type ComponentProps } from "react";

const root = "grid gap-5";
const group = "grid gap-2";
const heading =
  "flex items-center gap-2 px-1 text-xs font-medium text-muted transition-opacity duration-300 ease-out starting:opacity-0 motion-reduce:transition-none";
const count =
  "rounded-full bg-subtle px-1.5 text-[11px] leading-4 text-muted tabular-nums";
const list = "grid gap-1.5";
const itemClass =
  "relative flex items-center gap-3 rounded-xl border border-line bg-surface px-3 py-2.5 transition-colors duration-300 ease-out data-[pinned=true]:border-primary-line data-[pinned=true]:bg-primary-soft motion-reduce:transition-none";
const iconTile =
  "grid size-9 shrink-0 place-items-center rounded-lg bg-subtle text-ink transition-colors duration-300 ease-out in-data-[pinned=true]:bg-surface motion-reduce:transition-none";
const iconClass = "size-5";
const body = "grid min-w-0 flex-1";
const labelClass = "truncate text-sm font-medium text-ink";
const descriptionClass = "truncate text-xs text-muted";
const metaClass = "shrink-0 text-xs text-muted tabular-nums";
const pinButton =
  "group/pin grid size-8 shrink-0 place-items-center rounded-lg text-muted transition-colors duration-150 ease-out hover:bg-subtle hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary aria-pressed:text-ink motion-reduce:transition-none";
const pinIcon =
  "size-4 rotate-45 transition-transform duration-300 ease-[cubic-bezier(0.34,1.56,0.64,1)] group-aria-pressed/pin:rotate-0 group-aria-pressed/pin:fill-current motion-reduce:transition-none";
const srOnly = "sr-only";

const PIN_PATH =
  "M12 17v5M9 10.8a2 2 0 0 1-1.1 1.8l-1.8.9A2 2 0 0 0 5 15.2v.8a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.8a2 2 0 0 0-1.1-1.8l-1.8-.9a2 2 0 0 1-1.1-1.8V7a1 1 0 0 1 1-1 2 2 0 0 0 0-4H8a2 2 0 0 0 0 4 1 1 0 0 1 1 1z";
/** Length and curve of the move between groups. */
const FLIP_DURATION = 350;
const FLIP_EASING = "cubic-bezier(0.2, 0.8, 0.2, 1)";

const cx = (...c: (string | false | null | undefined)[]) =>
  c.filter(Boolean).join(" ");

const rows = (root: HTMLElement | null) =>
  Array.from(root?.querySelectorAll<HTMLElement>("[data-value]") ?? []);

/** Position of every row before the change, keyed by value. */
const measure = (root: HTMLElement | null) =>
  new Map(
    rows(root).map((row) => [row.dataset.value, row.getBoundingClientRect()]),
  );

/** FLIP: start each row where it was and let it glide to its new place, then refocus the moved pin button. */
function flip(
  root: HTMLElement | null,
  before: Map<string | undefined, DOMRect>,
  moved: string,
) {
  const still = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
  for (const row of rows(root)) {
    if (row.dataset.value === moved) row.querySelector("button")?.focus();
    const old = before.get(row.dataset.value);
    const now = row.getBoundingClientRect();
    if (still || !old || !row.animate) continue;
    const [x, y] = [old.left - now.left, old.top - now.top];
    if (!x && !y) continue;
    const zIndex = row.dataset.value === moved ? 1 : 0;
    row.animate(
      [
        { transform: `translate(${x}px, ${y}px)`, zIndex },
        { transform: "none", zIndex },
      ],
      { duration: FLIP_DURATION, easing: FLIP_EASING },
    );
  }
}

export type PinnedListItem = {
  value: string;
  label: string;
  description?: string;
  /** Short text on the right, such as a time or count. */
  meta?: string;
  /** Path data (the d attribute) for a 24x24 stroked icon. */
  icon?: string;
};

export type PinnedListProps = ComponentProps<"div"> & {
  items: PinnedListItem[];
  pinned?: string[];
  defaultPinned?: string[];
  onPinnedChange?: (pinned: string[]) => void;
  pinLabel?: string;
  unpinLabel?: string;
  pinnedLabel?: string;
  allLabel?: string;
  pinnedMessage?: string;
  unpinnedMessage?: string;
};

export function PinnedList({
  items,
  pinned,
  defaultPinned = [],
  onPinnedChange,
  pinLabel = "Pin {label}",
  unpinLabel = "Unpin {label}",
  pinnedLabel = "Pinned",
  allLabel = "All",
  pinnedMessage = "{label} pinned",
  unpinnedMessage = "{label} unpinned",
  className,
  ...props
}: PinnedListProps) {
  const rootRef = useRef<HTMLDivElement>(null);
  const pending = useRef<{
    before: Map<string | undefined, DOMRect>;
    moved: string;
  }>(null);
  const [inner, setInner] = useState(defaultPinned);
  const [message, setMessage] = useState("");
  const current = pinned ?? inner;

  useLayoutEffect(() => {
    if (!pending.current) return;
    flip(rootRef.current, pending.current.before, pending.current.moved);
    pending.current = null;
  }, [current]);

  const toggle = (item: PinnedListItem) => {
    const on = !current.includes(item.value);
    const next = on
      ? [...current, item.value]
      : current.filter((value) => value !== item.value);
    pending.current = { before: measure(rootRef.current), moved: item.value };
    setInner(next);
    setMessage(
      (on ? pinnedMessage : unpinnedMessage).replace("{label}", item.label),
    );
    onPinnedChange?.(next);
  };

  const groups = [
    {
      label: pinnedLabel,
      items: items.filter((item) => current.includes(item.value)),
    },
    {
      label: allLabel,
      items: items.filter((item) => !current.includes(item.value)),
    },
  ];

  return (
    <div ref={rootRef} className={cx(root, className)} {...props}>
      {groups.map((part, index) => (
        <div key={index} hidden={!part.items.length} className={group}>
          <p className={heading}>
            {part.label}
            <span className={count}>{part.items.length}</span>
          </p>
          <ul aria-label={part.label} className={list}>
            {part.items.map((item) => {
              const on = current.includes(item.value);
              return (
                <li
                  key={item.value}
                  data-value={item.value}
                  data-pinned={on}
                  className={itemClass}
                >
                  {item.icon && (
                    <span aria-hidden="true" className={iconTile}>
                      <svg
                        className={iconClass}
                        viewBox="0 0 24 24"
                        fill="none"
                        stroke="currentColor"
                        strokeWidth="1.5"
                        strokeLinecap="round"
                        strokeLinejoin="round"
                      >
                        <path d={item.icon} />
                      </svg>
                    </span>
                  )}
                  <span className={body}>
                    <span className={labelClass}>{item.label}</span>
                    {item.description && (
                      <span className={descriptionClass}>
                        {item.description}
                      </span>
                    )}
                  </span>
                  {item.meta && <span className={metaClass}>{item.meta}</span>}
                  <button
                    type="button"
                    aria-pressed={on}
                    aria-label={pinLabel.replace("{label}", item.label)}
                    title={(on ? unpinLabel : pinLabel).replace(
                      "{label}",
                      item.label,
                    )}
                    className={pinButton}
                    onClick={() => toggle(item)}
                  >
                    <svg
                      className={pinIcon}
                      viewBox="0 0 24 24"
                      fill="none"
                      stroke="currentColor"
                      strokeWidth="1.5"
                      strokeLinecap="round"
                      strokeLinejoin="round"
                      aria-hidden="true"
                    >
                      <path d={PIN_PATH} />
                    </svg>
                  </button>
                </li>
              );
            })}
          </ul>
        </div>
      ))}
      <p role="status" className={srOnly}>
        {message}
      </p>
    </div>
  );
}
```

```tsx
import { PinnedList } from "@/components/markas/PinnedList";

const [pinned, setPinned] = useState<string[]>(["design"]);

<PinnedList items={channels} pinned={pinned} onPinnedChange={setPinned} />;
```

### Vue

Save at `src/components/markas/PinnedList.vue`. No extra dependencies.

```vue
<script setup lang="ts">
import { computed, nextTick, ref } from "vue";

export type PinnedListItem = {
  value: string;
  label: string;
  description?: string;
  /** Short text on the right, such as a time or count. */
  meta?: string;
  /** Path data (the d attribute) for a 24x24 stroked icon. */
  icon?: string;
};

const props = withDefaults(
  defineProps<{
    items: PinnedListItem[];
    defaultPinned?: string[];
    pinLabel?: string;
    unpinLabel?: string;
    pinnedLabel?: string;
    allLabel?: string;
    pinnedMessage?: string;
    unpinnedMessage?: string;
  }>(),
  {
    defaultPinned: () => [],
    pinLabel: "Pin {label}",
    unpinLabel: "Unpin {label}",
    pinnedLabel: "Pinned",
    allLabel: "All",
    pinnedMessage: "{label} pinned",
    unpinnedMessage: "{label} unpinned",
  },
);
const model = defineModel<string[]>("pinned");

const root = "grid gap-5";
const group = "grid gap-2";
const heading =
  "flex items-center gap-2 px-1 text-xs font-medium text-muted transition-opacity duration-300 ease-out starting:opacity-0 motion-reduce:transition-none";
const count =
  "rounded-full bg-subtle px-1.5 text-[11px] leading-4 text-muted tabular-nums";
const list = "grid gap-1.5";
const itemClass =
  "relative flex items-center gap-3 rounded-xl border border-line bg-surface px-3 py-2.5 transition-colors duration-300 ease-out data-[pinned=true]:border-primary-line data-[pinned=true]:bg-primary-soft motion-reduce:transition-none";
const iconTile =
  "grid size-9 shrink-0 place-items-center rounded-lg bg-subtle text-ink transition-colors duration-300 ease-out in-data-[pinned=true]:bg-surface motion-reduce:transition-none";
const iconClass = "size-5";
const body = "grid min-w-0 flex-1";
const labelClass = "truncate text-sm font-medium text-ink";
const descriptionClass = "truncate text-xs text-muted";
const metaClass = "shrink-0 text-xs text-muted tabular-nums";
const pinButton =
  "group/pin grid size-8 shrink-0 place-items-center rounded-lg text-muted transition-colors duration-150 ease-out hover:bg-subtle hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary aria-pressed:text-ink motion-reduce:transition-none";
const pinIcon =
  "size-4 rotate-45 transition-transform duration-300 ease-[cubic-bezier(0.34,1.56,0.64,1)] group-aria-pressed/pin:rotate-0 group-aria-pressed/pin:fill-current motion-reduce:transition-none";
const srOnly = "sr-only";

const PIN_PATH =
  "M12 17v5M9 10.8a2 2 0 0 1-1.1 1.8l-1.8.9A2 2 0 0 0 5 15.2v.8a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.8a2 2 0 0 0-1.1-1.8l-1.8-.9a2 2 0 0 1-1.1-1.8V7a1 1 0 0 1 1-1 2 2 0 0 0 0-4H8a2 2 0 0 0 0 4 1 1 0 0 1 1 1z";
/** Length and curve of the move between groups. */
const FLIP_DURATION = 350;
const FLIP_EASING = "cubic-bezier(0.2, 0.8, 0.2, 1)";

const rows = (el: HTMLElement | undefined) =>
  Array.from(el?.querySelectorAll<HTMLElement>("[data-value]") ?? []);

/** Position of every row before the change, keyed by value. */
const measure = (el: HTMLElement | undefined) =>
  new Map(
    rows(el).map((row) => [row.dataset.value, row.getBoundingClientRect()]),
  );

/** FLIP: start each row where it was and let it glide to its new place, then refocus the moved pin button. */
function flip(
  el: HTMLElement | undefined,
  before: Map<string | undefined, DOMRect>,
  moved: string,
) {
  const still = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
  for (const row of rows(el)) {
    if (row.dataset.value === moved) row.querySelector("button")?.focus();
    const old = before.get(row.dataset.value);
    const now = row.getBoundingClientRect();
    if (still || !old || !row.animate) continue;
    const [x, y] = [old.left - now.left, old.top - now.top];
    if (!x && !y) continue;
    const zIndex = row.dataset.value === moved ? 1 : 0;
    row.animate(
      [
        { transform: `translate(${x}px, ${y}px)`, zIndex },
        { transform: "none", zIndex },
      ],
      { duration: FLIP_DURATION, easing: FLIP_EASING },
    );
  }
}

const rootEl = ref<HTMLElement>();
const inner = ref(props.defaultPinned);
const message = ref("");
const current = computed(() => model.value ?? inner.value);
const groups = computed(() => [
  {
    label: props.pinnedLabel,
    items: props.items.filter((item) => current.value.includes(item.value)),
  },
  {
    label: props.allLabel,
    items: props.items.filter((item) => !current.value.includes(item.value)),
  },
]);

async function toggle(item: PinnedListItem) {
  const on = !current.value.includes(item.value);
  const next = on
    ? [...current.value, item.value]
    : current.value.filter((value) => value !== item.value);
  const before = measure(rootEl.value);
  inner.value = next;
  model.value = next;
  message.value = (on ? props.pinnedMessage : props.unpinnedMessage).replace(
    "{label}",
    item.label,
  );
  await nextTick();
  flip(rootEl.value, before, item.value);
}
</script>

<template>
  <div ref="rootEl" :class="root">
    <div
      v-for="(part, index) in groups"
      :key="index"
      :hidden="!part.items.length"
      :class="group"
    >
      <p :class="heading">
        {{ part.label }}<span :class="count">{{ part.items.length }}</span>
      </p>
      <ul :aria-label="part.label" :class="list">
        <li
          v-for="item in part.items"
          :key="item.value"
          :data-value="item.value"
          :data-pinned="current.includes(item.value)"
          :class="itemClass"
        >
          <span v-if="item.icon" aria-hidden="true" :class="iconTile">
            <svg
              :class="iconClass"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="1.5"
              stroke-linecap="round"
              stroke-linejoin="round"
            >
              <path :d="item.icon" />
            </svg>
          </span>
          <span :class="body">
            <span :class="labelClass">{{ item.label }}</span>
            <span v-if="item.description" :class="descriptionClass">{{
              item.description
            }}</span>
          </span>
          <span v-if="item.meta" :class="metaClass">{{ item.meta }}</span>
          <button
            type="button"
            :aria-pressed="current.includes(item.value) ? 'true' : 'false'"
            :aria-label="props.pinLabel.replace('{label}', item.label)"
            :title="
              (current.includes(item.value)
                ? props.unpinLabel
                : props.pinLabel
              ).replace('{label}', item.label)
            "
            :class="pinButton"
            @click="toggle(item)"
          >
            <svg
              :class="pinIcon"
              viewBox="0 0 24 24"
              fill="none"
              stroke="currentColor"
              stroke-width="1.5"
              stroke-linecap="round"
              stroke-linejoin="round"
              aria-hidden="true"
            >
              <path :d="PIN_PATH" />
            </svg>
          </button>
        </li>
      </ul>
    </div>
    <p role="status" :class="srOnly">{{ message }}</p>
  </div>
</template>
```

```vue
<script setup lang="ts">
import { ref } from "vue";
import PinnedList from "@/components/markas/PinnedList.vue";

const pinned = ref(["design"]);
</script>

<template>
  <PinnedList v-model:pinned="pinned" :items="channels" />
</template>
```

### Svelte

Save at `src/lib/components/markas/PinnedList.svelte`. No extra dependencies.

```svelte
<script lang="ts" module>
  export type PinnedListItem = {
    value: string;
    label: string;
    description?: string;
    /** Short text on the right, such as a time or count. */
    meta?: string;
    /** Path data (the d attribute) for a 24x24 stroked icon. */
    icon?: string;
  };
</script>

<script lang="ts">
  import { tick } from "svelte";
  import type { HTMLAttributes } from "svelte/elements";

  const root = "grid gap-5";
  const group = "grid gap-2";
  const heading =
    "flex items-center gap-2 px-1 text-xs font-medium text-muted transition-opacity duration-300 ease-out starting:opacity-0 motion-reduce:transition-none";
  const count =
    "rounded-full bg-subtle px-1.5 text-[11px] leading-4 text-muted tabular-nums";
  const list = "grid gap-1.5";
  const itemClass =
    "relative flex items-center gap-3 rounded-xl border border-line bg-surface px-3 py-2.5 transition-colors duration-300 ease-out data-[pinned=true]:border-primary-line data-[pinned=true]:bg-primary-soft motion-reduce:transition-none";
  const iconTile =
    "grid size-9 shrink-0 place-items-center rounded-lg bg-subtle text-ink transition-colors duration-300 ease-out in-data-[pinned=true]:bg-surface motion-reduce:transition-none";
  const iconClass = "size-5";
  const body = "grid min-w-0 flex-1";
  const labelClass = "truncate text-sm font-medium text-ink";
  const descriptionClass = "truncate text-xs text-muted";
  const metaClass = "shrink-0 text-xs text-muted tabular-nums";
  const pinButton =
    "group/pin grid size-8 shrink-0 place-items-center rounded-lg text-muted transition-colors duration-150 ease-out hover:bg-subtle hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary aria-pressed:text-ink motion-reduce:transition-none";
  const pinIcon =
    "size-4 rotate-45 transition-transform duration-300 ease-[cubic-bezier(0.34,1.56,0.64,1)] group-aria-pressed/pin:rotate-0 group-aria-pressed/pin:fill-current motion-reduce:transition-none";
  const srOnly = "sr-only";

  const PIN_PATH =
    "M12 17v5M9 10.8a2 2 0 0 1-1.1 1.8l-1.8.9A2 2 0 0 0 5 15.2v.8a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.8a2 2 0 0 0-1.1-1.8l-1.8-.9a2 2 0 0 1-1.1-1.8V7a1 1 0 0 1 1-1 2 2 0 0 0 0-4H8a2 2 0 0 0 0 4 1 1 0 0 1 1 1z";
  /** Length and curve of the move between groups. */
  const FLIP_DURATION = 350;
  const FLIP_EASING = "cubic-bezier(0.2, 0.8, 0.2, 1)";

  const rows = (el: HTMLElement | undefined) =>
    Array.from(el?.querySelectorAll<HTMLElement>("[data-value]") ?? []);

  /** Position of every row before the change, keyed by value. */
  const measure = (el: HTMLElement | undefined) =>
    new Map(
      rows(el).map((row) => [row.dataset.value, row.getBoundingClientRect()]),
    );

  /** FLIP: start each row where it was and let it glide to its new place, then refocus the moved pin button. */
  function flip(
    el: HTMLElement | undefined,
    before: Map<string | undefined, DOMRect>,
    moved: string,
  ) {
    const still = window.matchMedia?.(
      "(prefers-reduced-motion: reduce)",
    ).matches;
    for (const row of rows(el)) {
      if (row.dataset.value === moved) row.querySelector("button")?.focus();
      const old = before.get(row.dataset.value);
      const now = row.getBoundingClientRect();
      if (still || !old || !row.animate) continue;
      const [x, y] = [old.left - now.left, old.top - now.top];
      if (!x && !y) continue;
      const zIndex = row.dataset.value === moved ? 1 : 0;
      row.animate(
        [
          { transform: `translate(${x}px, ${y}px)`, zIndex },
          { transform: "none", zIndex },
        ],
        { duration: FLIP_DURATION, easing: FLIP_EASING },
      );
    }
  }

  type Props = HTMLAttributes<HTMLDivElement> & {
    items: PinnedListItem[];
    /** Pinned values, bindable with bind:pinned. */
    pinned?: string[];
    defaultPinned?: string[];
    onPinnedChange?: (pinned: string[]) => void;
    pinLabel?: string;
    unpinLabel?: string;
    pinnedLabel?: string;
    allLabel?: string;
    pinnedMessage?: string;
    unpinnedMessage?: string;
  };

  let {
    items,
    pinned = $bindable(),
    defaultPinned = [],
    onPinnedChange,
    pinLabel = "Pin {label}",
    unpinLabel = "Unpin {label}",
    pinnedLabel = "Pinned",
    allLabel = "All",
    pinnedMessage = "{label} pinned",
    unpinnedMessage = "{label} unpinned",
    class: className,
    ...rest
  }: Props = $props();

  let rootEl = $state<HTMLDivElement>();
  // svelte-ignore state_referenced_locally
  let inner = $state(defaultPinned);
  let message = $state("");
  const current = $derived(pinned ?? inner);
  const groups = $derived([
    {
      label: pinnedLabel,
      items: items.filter((item) => current.includes(item.value)),
    },
    {
      label: allLabel,
      items: items.filter((item) => !current.includes(item.value)),
    },
  ]);

  async function toggle(item: PinnedListItem) {
    const on = !current.includes(item.value);
    const next = on
      ? [...current, item.value]
      : current.filter((value) => value !== item.value);
    const before = measure(rootEl);
    inner = next;
    pinned = next;
    message = (on ? pinnedMessage : unpinnedMessage).replace(
      "{label}",
      item.label,
    );
    onPinnedChange?.(next);
    await tick();
    flip(rootEl, before, item.value);
  }
</script>

<div bind:this={rootEl} class={[root, className]} {...rest}>
  {#each groups as part, index (index)}
    <div hidden={!part.items.length} class={group}>
      <p class={heading}>
        {part.label}<span class={count}>{part.items.length}</span>
      </p>
      <ul aria-label={part.label} class={list}>
        {#each part.items as item (item.value)}
          {@const on = current.includes(item.value)}
          <li data-value={item.value} data-pinned={on} class={itemClass}>
            {#if item.icon}
              <span aria-hidden="true" class={iconTile}>
                <svg
                  class={iconClass}
                  viewBox="0 0 24 24"
                  fill="none"
                  stroke="currentColor"
                  stroke-width="1.5"
                  stroke-linecap="round"
                  stroke-linejoin="round"
                >
                  <path d={item.icon} />
                </svg>
              </span>
            {/if}
            <span class={body}>
              <span class={labelClass}>{item.label}</span>
              {#if item.description}
                <span class={descriptionClass}>{item.description}</span>
              {/if}
            </span>
            {#if item.meta}
              <span class={metaClass}>{item.meta}</span>
            {/if}
            <button
              type="button"
              aria-pressed={on}
              aria-label={pinLabel.replace("{label}", item.label)}
              title={(on ? unpinLabel : pinLabel).replace(
                "{label}",
                item.label,
              )}
              class={pinButton}
              onclick={() => toggle(item)}
            >
              <svg
                class={pinIcon}
                viewBox="0 0 24 24"
                fill="none"
                stroke="currentColor"
                stroke-width="1.5"
                stroke-linecap="round"
                stroke-linejoin="round"
                aria-hidden="true"
              >
                <path d={PIN_PATH} />
              </svg>
            </button>
          </li>
        {/each}
      </ul>
    </div>
  {/each}
  <p role="status" class={srOnly}>{message}</p>
</div>
```

```svelte
<script lang="ts">
  import PinnedList from "$lib/components/markas/PinnedList.svelte";

  const items = [
    { value: "roadmap", label: "Q4 roadmap", description: "Product, 14 pages" },
    { value: "standup", label: "Standup notes", description: "Team, daily" },
  ];
  let pinned = $state(["roadmap"]);
</script>

<PinnedList {items} bind:pinned />
```

### Astro

Save at `src/components/markas/PinnedList.astro`. No extra dependencies.

```astro
---
import type { HTMLAttributes } from "astro/types";

const root = "grid gap-5";
const group = "grid gap-2";
const heading =
  "flex items-center gap-2 px-1 text-xs font-medium text-muted transition-opacity duration-300 ease-out starting:opacity-0 motion-reduce:transition-none";
const count =
  "rounded-full bg-subtle px-1.5 text-[11px] leading-4 text-muted tabular-nums";
const list = "grid gap-1.5";
const itemClass =
  "relative flex items-center gap-3 rounded-xl border border-line bg-surface px-3 py-2.5 transition-colors duration-300 ease-out data-[pinned=true]:border-primary-line data-[pinned=true]:bg-primary-soft motion-reduce:transition-none";
const iconTile =
  "grid size-9 shrink-0 place-items-center rounded-lg bg-subtle text-ink transition-colors duration-300 ease-out in-data-[pinned=true]:bg-surface motion-reduce:transition-none";
const iconClass = "size-5";
const body = "grid min-w-0 flex-1";
const labelClass = "truncate text-sm font-medium text-ink";
const descriptionClass = "truncate text-xs text-muted";
const metaClass = "shrink-0 text-xs text-muted tabular-nums";
const pinButton =
  "group/pin grid size-8 shrink-0 place-items-center rounded-lg text-muted transition-colors duration-150 ease-out hover:bg-subtle hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary aria-pressed:text-ink motion-reduce:transition-none";
const pinIcon =
  "size-4 rotate-45 transition-transform duration-300 ease-[cubic-bezier(0.34,1.56,0.64,1)] group-aria-pressed/pin:rotate-0 group-aria-pressed/pin:fill-current motion-reduce:transition-none";
const srOnly = "sr-only";

const PIN_PATH =
  "M12 17v5M9 10.8a2 2 0 0 1-1.1 1.8l-1.8.9A2 2 0 0 0 5 15.2v.8a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.8a2 2 0 0 0-1.1-1.8l-1.8-.9a2 2 0 0 1-1.1-1.8V7a1 1 0 0 1 1-1 2 2 0 0 0 0-4H8a2 2 0 0 0 0 4 1 1 0 0 1 1 1z";

export type PinnedListItem = {
  value: string;
  label: string;
  description?: string;
  /** Short text on the right, such as a time or count. */
  meta?: string;
  /** Path data (the d attribute) for a 24x24 stroked icon. */
  icon?: string;
};

type Props = HTMLAttributes<"div"> & {
  items: PinnedListItem[];
  defaultPinned?: string[];
  pinLabel?: string;
  unpinLabel?: string;
  pinnedLabel?: string;
  allLabel?: string;
  pinnedMessage?: string;
  unpinnedMessage?: string;
};

const {
  items,
  defaultPinned = [],
  pinLabel = "Pin {label}",
  unpinLabel = "Unpin {label}",
  pinnedLabel = "Pinned",
  allLabel = "All",
  pinnedMessage = "{label} pinned",
  unpinnedMessage = "{label} unpinned",
  class: className,
  ...rest
} = Astro.props;

const indexed = items.map((item, index) => ({ ...item, index }));
const groups = [
  {
    label: pinnedLabel,
    items: defaultPinned
      .map((value) => indexed.find((item) => item.value === value))
      .filter((item) => item !== undefined),
  },
  {
    label: allLabel,
    items: indexed.filter((item) => !defaultPinned.includes(item.value)),
  },
];
---

<div
  class:list={[root, className]}
  data-markas-pinned-list
  data-pin-label={pinLabel}
  data-unpin-label={unpinLabel}
  data-pinned-message={pinnedMessage}
  data-unpinned-message={unpinnedMessage}
  {...rest}
>
  {
    groups.map((part) => (
      <div hidden={!part.items.length} class={group}>
        <p class={heading}>
          {part.label}<span class={count} data-markas-pinned-count>{part.items.length}</span>
        </p>
        <ul aria-label={part.label} class={list}>
          {part.items.map((item) => {
            const on = defaultPinned.includes(item.value);
            return (
              <li
                data-value={item.value}
                data-pinned={String(on)}
                data-index={item.index}
                data-label={item.label}
                class={itemClass}
              >
                {item.icon && (
                  <span aria-hidden="true" class={iconTile}>
                    <svg
                      class={iconClass}
                      viewBox="0 0 24 24"
                      fill="none"
                      stroke="currentColor"
                      stroke-width="1.5"
                      stroke-linecap="round"
                      stroke-linejoin="round"
                    >
                      <path d={item.icon} />
                    </svg>
                  </span>
                )}
                <span class={body}>
                  <span class={labelClass}>{item.label}</span>
                  {item.description && (
                    <span class={descriptionClass}>{item.description}</span>
                  )}
                </span>
                {item.meta && <span class={metaClass}>{item.meta}</span>}
                <button
                  type="button"
                  aria-pressed={on ? "true" : "false"}
                  aria-label={pinLabel.replace("{label}", item.label)}
                  title={(on ? unpinLabel : pinLabel).replace(
                    "{label}",
                    item.label,
                  )}
                  class={pinButton}
                  data-markas-pin
                >
                  <svg
                    class={pinIcon}
                    viewBox="0 0 24 24"
                    fill="none"
                    stroke="currentColor"
                    stroke-width="1.5"
                    stroke-linecap="round"
                    stroke-linejoin="round"
                    aria-hidden="true"
                  >
                    <path d={PIN_PATH} />
                  </svg>
                </button>
              </li>
            );
          })}
        </ul>
      </div>
    ))
  }
  <p role="status" class={srOnly}></p>
</div>

<script>
  /** Length and curve of the move between groups. */
  const FLIP_DURATION = 350;
  const FLIP_EASING = "cubic-bezier(0.2, 0.8, 0.2, 1)";

  const rows = (host: HTMLElement) =>
    Array.from(host.querySelectorAll<HTMLElement>("[data-value]"));

  /** FLIP: start each row where it was and let it glide to its new place, then refocus the moved pin button. */
  function flip(
    host: HTMLElement,
    before: Map<string | undefined, DOMRect>,
    moved: string,
  ) {
    const still = window.matchMedia?.(
      "(prefers-reduced-motion: reduce)",
    ).matches;
    for (const row of rows(host)) {
      if (row.dataset.value === moved) row.querySelector("button")?.focus();
      const old = before.get(row.dataset.value);
      const now = row.getBoundingClientRect();
      if (still || !old || !row.animate) continue;
      const [x, y] = [old.left - now.left, old.top - now.top];
      if (!x && !y) continue;
      const zIndex = row.dataset.value === moved ? 1 : 0;
      row.animate(
        [
          { transform: `translate(${x}px, ${y}px)`, zIndex },
          { transform: "none", zIndex },
        ],
        { duration: FLIP_DURATION, easing: FLIP_EASING },
      );
    }
  }

  // One listener per page serves every list. Pinning moves the row into the Pinned group; unpinning
  // puts it back in its original place in All. A change event carries the pinned values.
  document.addEventListener("click", (event) => {
    const button = (event.target as Element).closest<HTMLButtonElement>(
      "[data-markas-pin]",
    );
    const host = button?.closest<HTMLElement>("[data-markas-pinned-list]");
    const row = button?.closest<HTMLElement>("li[data-value]");
    const [pinnedList, allList] = host?.querySelectorAll("ul") ?? [];
    if (!button || !host || !row || !pinnedList || !allList) return;
    const value = row.dataset.value ?? "";
    const label = row.dataset.label ?? "";
    const on = row.dataset.pinned !== "true";
    const before = new Map(
      rows(host).map((item) => [
        item.dataset.value,
        item.getBoundingClientRect(),
      ]),
    );
    if (on) pinnedList.append(row);
    else {
      const index = Number(row.dataset.index);
      const next = [...allList.children].find(
        (item) => Number((item as HTMLElement).dataset.index) > index,
      );
      allList.insertBefore(row, next ?? null);
    }
    row.dataset.pinned = String(on);
    button.setAttribute("aria-pressed", String(on));
    button.title = (
      (on ? host.dataset.unpinLabel : host.dataset.pinLabel) ?? ""
    ).replace("{label}", label);
    for (const list of [pinnedList, allList]) {
      const part = list.parentElement!;
      part.hidden = !list.children.length;
      const counter = part.querySelector("[data-markas-pinned-count]");
      if (counter) counter.textContent = String(list.children.length);
    }
    const status = host.querySelector("[role=status]");
    if (status)
      status.textContent = (
        (on ? host.dataset.pinnedMessage : host.dataset.unpinnedMessage) ?? ""
      ).replace("{label}", label);
    const pinned = [...pinnedList.children].map(
      (item) => (item as HTMLElement).dataset.value ?? "",
    );
    host.dispatchEvent(
      new CustomEvent("change", { detail: pinned, bubbles: true }),
    );
    flip(host, before, value);
  });
</script>
```

```astro
---
import PinnedList from "@/components/markas/PinnedList.astro";

const items = [
  { value: "roadmap", label: "Q4 roadmap", description: "Product, 14 pages" },
  { value: "standup", label: "Standup notes", description: "Team, daily" },
];
---

<PinnedList items={items} defaultPinned={["roadmap"]} />
```

A small bundled script moves the rows and dispatches `change` with the pinned values.

### Angular

Save at `src/app/markas/pinned-list.component.ts`. No extra dependencies.

```ts
import {
  ChangeDetectionStrategy,
  Component,
  computed,
  type ElementRef,
  ChangeDetectorRef,
  inject,
  input,
  linkedSignal,
  output,
  signal,
  viewChild,
} from "@angular/core";

const root = "grid gap-5";
const group = "grid gap-2";
const heading =
  "flex items-center gap-2 px-1 text-xs font-medium text-muted transition-opacity duration-300 ease-out starting:opacity-0 motion-reduce:transition-none";
const count =
  "rounded-full bg-subtle px-1.5 text-[11px] leading-4 text-muted tabular-nums";
const list = "grid gap-1.5";
const itemClass =
  "relative flex items-center gap-3 rounded-xl border border-line bg-surface px-3 py-2.5 transition-colors duration-300 ease-out data-[pinned=true]:border-primary-line data-[pinned=true]:bg-primary-soft motion-reduce:transition-none";
const iconTile =
  "grid size-9 shrink-0 place-items-center rounded-lg bg-subtle text-ink transition-colors duration-300 ease-out in-data-[pinned=true]:bg-surface motion-reduce:transition-none";
const iconClass = "size-5";
const body = "grid min-w-0 flex-1";
const labelClass = "truncate text-sm font-medium text-ink";
const descriptionClass = "truncate text-xs text-muted";
const metaClass = "shrink-0 text-xs text-muted tabular-nums";
const pinButton =
  "group/pin grid size-8 shrink-0 place-items-center rounded-lg text-muted transition-colors duration-150 ease-out hover:bg-subtle hover:text-ink focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-primary aria-pressed:text-ink motion-reduce:transition-none";
const pinIcon =
  "size-4 rotate-45 transition-transform duration-300 ease-[cubic-bezier(0.34,1.56,0.64,1)] group-aria-pressed/pin:rotate-0 group-aria-pressed/pin:fill-current motion-reduce:transition-none";
const srOnly = "sr-only";

const PIN_PATH =
  "M12 17v5M9 10.8a2 2 0 0 1-1.1 1.8l-1.8.9A2 2 0 0 0 5 15.2v.8a1 1 0 0 0 1 1h12a1 1 0 0 0 1-1v-.8a2 2 0 0 0-1.1-1.8l-1.8-.9a2 2 0 0 1-1.1-1.8V7a1 1 0 0 1 1-1 2 2 0 0 0 0-4H8a2 2 0 0 0 0 4 1 1 0 0 1 1 1z";
/** Length and curve of the move between groups. */
const FLIP_DURATION = 350;
const FLIP_EASING = "cubic-bezier(0.2, 0.8, 0.2, 1)";

const rows = (el: HTMLElement) =>
  Array.from(el.querySelectorAll<HTMLElement>("[data-value]"));

/** Position of every row before the change, keyed by value. */
const measure = (el: HTMLElement) =>
  new Map(
    rows(el).map((row) => [row.dataset.value, row.getBoundingClientRect()]),
  );

/** FLIP: start each row where it was and let it glide to its new place, then refocus the moved pin button. */
function flip(
  el: HTMLElement,
  before: Map<string | undefined, DOMRect>,
  moved: string,
) {
  const still = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches;
  for (const row of rows(el)) {
    if (row.dataset.value === moved) row.querySelector("button")?.focus();
    const old = before.get(row.dataset.value);
    const now = row.getBoundingClientRect();
    if (still || !old || !row.animate) continue;
    const [x, y] = [old.left - now.left, old.top - now.top];
    if (!x && !y) continue;
    const zIndex = row.dataset.value === moved ? 1 : 0;
    row.animate(
      [
        { transform: `translate(${x}px, ${y}px)`, zIndex },
        { transform: "none", zIndex },
      ],
      { duration: FLIP_DURATION, easing: FLIP_EASING },
    );
  }
}

export type PinnedListItem = {
  value: string;
  label: string;
  description?: string;
  /** Short text on the right, such as a time or count. */
  meta?: string;
  /** Path data (the d attribute) for a 24x24 stroked icon. */
  icon?: string;
};

/**
 * Pinning moves a row into the Pinned group with a FLIP animation. Supports [(pinned)].
 * The host stays out of layout; the user's class lands on the list.
 */
@Component({
  selector: "markas-pinned-list",
  changeDetection: ChangeDetectionStrategy.OnPush,
  host: { class: "contents" },
  template: `
    <div #rootEl [class]="classes()">
      @for (part of groups(); track $index) {
        <div [hidden]="!part.items.length" [class]="group">
          <p [class]="heading">
            {{ part.label }}<span [class]="count">{{ part.items.length }}</span>
          </p>
          <ul [attr.aria-label]="part.label" [class]="list">
            @for (item of part.items; track item.value) {
              <li
                [attr.data-value]="item.value"
                [attr.data-pinned]="current().includes(item.value)"
                [class]="itemClass"
              >
                @if (item.icon) {
                  <span aria-hidden="true" [class]="iconTile">
                    <svg
                      [class]="iconClass"
                      viewBox="0 0 24 24"
                      fill="none"
                      stroke="currentColor"
                      stroke-width="1.5"
                      stroke-linecap="round"
                      stroke-linejoin="round"
                    >
                      <path [attr.d]="item.icon" />
                    </svg>
                  </span>
                }
                <span [class]="body">
                  <span [class]="labelClass">{{ item.label }}</span>
                  @if (item.description) {
                    <span [class]="descriptionClass">{{
                      item.description
                    }}</span>
                  }
                </span>
                @if (item.meta) {
                  <span [class]="metaClass">{{ item.meta }}</span>
                }
                <button
                  type="button"
                  [attr.aria-pressed]="current().includes(item.value)"
                  [attr.aria-label]="label(pinLabel(), item)"
                  [attr.title]="
                    label(
                      current().includes(item.value)
                        ? unpinLabel()
                        : pinLabel(),
                      item
                    )
                  "
                  [class]="pinButton"
                  (click)="toggle(item)"
                >
                  <svg
                    [class]="pinIcon"
                    viewBox="0 0 24 24"
                    fill="none"
                    stroke="currentColor"
                    stroke-width="1.5"
                    stroke-linecap="round"
                    stroke-linejoin="round"
                    aria-hidden="true"
                  >
                    <path [attr.d]="PIN_PATH" />
                  </svg>
                </button>
              </li>
            }
          </ul>
        </div>
      }
      <p role="status" [class]="srOnly">{{ message() }}</p>
    </div>
  `,
})
export class PinnedList {
  readonly items = input.required<PinnedListItem[]>();
  readonly pinned = input<string[]>();
  readonly defaultPinned = input<string[]>([]);
  readonly pinLabel = input("Pin {label}");
  readonly unpinLabel = input("Unpin {label}");
  readonly pinnedLabel = input("Pinned");
  readonly allLabel = input("All");
  readonly pinnedMessage = input("{label} pinned");
  readonly unpinnedMessage = input("{label} unpinned");
  readonly userClass = input("", { alias: "class" });
  /** Emits the pinned values after every change. */
  readonly pinnedChange = output<string[]>();

  protected readonly group = group;
  protected readonly heading = heading;
  protected readonly count = count;
  protected readonly list = list;
  protected readonly itemClass = itemClass;
  protected readonly iconTile = iconTile;
  protected readonly iconClass = iconClass;
  protected readonly body = body;
  protected readonly labelClass = labelClass;
  protected readonly descriptionClass = descriptionClass;
  protected readonly metaClass = metaClass;
  protected readonly pinButton = pinButton;
  protected readonly pinIcon = pinIcon;
  protected readonly srOnly = srOnly;
  protected readonly PIN_PATH = PIN_PATH;

  protected readonly classes = computed(() =>
    [root, this.userClass()].filter(Boolean).join(" "),
  );
  protected readonly current = linkedSignal(
    () => this.pinned() ?? this.defaultPinned(),
  );
  protected readonly message = signal("");
  protected readonly groups = computed(() => [
    {
      label: this.pinnedLabel(),
      items: this.items().filter((item) => this.current().includes(item.value)),
    },
    {
      label: this.allLabel(),
      items: this.items().filter(
        (item) => !this.current().includes(item.value),
      ),
    },
  ]);
  private readonly rootEl =
    viewChild.required<ElementRef<HTMLDivElement>>("rootEl");
  private readonly changes = inject(ChangeDetectorRef);

  protected label(template: string, item: PinnedListItem) {
    return template.replace("{label}", item.label);
  }

  protected toggle(item: PinnedListItem) {
    const current = this.current();
    const on = !current.includes(item.value);
    const next = on
      ? [...current, item.value]
      : current.filter((value) => value !== item.value);
    const el = this.rootEl().nativeElement;
    const before = measure(el);
    this.current.set(next);
    this.message.set(
      this.label(on ? this.pinnedMessage() : this.unpinnedMessage(), item),
    );
    this.pinnedChange.emit(next);
    // Render now so the rows can glide from their old place in the same frame.
    this.changes.detectChanges();
    flip(el, before, item.value);
  }
}
```

```ts
import { Component, signal } from "@angular/core";
import { PinnedList } from "./markas/pinned-list.component";

@Component({
  selector: "app-docs",
  imports: [PinnedList],
  template: `<markas-pinned-list [items]="items" [(pinned)]="pinned" />`,
})
export class Docs {
  readonly items = [
    { value: "roadmap", label: "Q4 roadmap", description: "Product, 14 pages" },
    { value: "standup", label: "Standup notes", description: "Team, daily" },
  ];
  readonly pinned = signal(["roadmap"]);
}
```

## Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `items` | `{ value: string; label: string; description?: string; meta?: string; icon?: string }[]` | [] | Rows in their natural order. icon is the d attribute of a 24x24 stroked SVG path, meta is short text on the right. |
| `pinned / v-model:pinned` | `string[]` | - | Controlled pinned values in React (with onPinnedChange) and Vue (v-model:pinned). |
| `defaultPinned` | `string[]` | [] | Values pinned on first render. |
| `onPinnedChange / x-on:change` | `(pinned: string[]) => void` | - | Fires after a pin or unpin with the new list. Blade dispatches a change DOM event with the list as detail. |
| `pinLabel` | `string` | Pin {label} | Accessible name of each pin button. It stays the same while pinned, aria-pressed carries the state. |
| `unpinLabel` | `string` | Unpin {label} | Hover hint (title) of the pin button while the row is pinned. |
| `pinnedLabel` | `string` | Pinned | Heading and list name of the pinned group. |
| `allLabel` | `string` | All | Heading and list name of the other rows. |
| `pinnedMessage` | `string` | {label} pinned | Announced in the live region after pinning. |
| `unpinnedMessage` | `string` | {label} unpinned | Announced in the live region after unpinning. |
| `pinnedChange` | `output<string[]>` | - | Angular only. Emits the pinned values after every change; supports [(pinned)]. Svelte uses bind:pinned or onPinnedChange, Astro dispatches change. |

## Accessibility

- Each pin button is a toggle button with aria-pressed and a fixed name from pinLabel.
- Both groups are lists named by pinnedLabel and allLabel. An empty group is hidden.
- Focus follows the moved row to its pin button, and a status live region announces pinnedMessage or unpinnedMessage.
- With reduced motion rows jump to their new place without the FLIP glide.

## Notes

- Pinned rows keep the order of items, so unpinning returns a row to its original place.
- The move uses FLIP: every row is measured before and after the change and animated from the old spot with the Web Animations API. No layout library is needed.
- {label} in pinLabel, unpinLabel, pinnedMessage, and unpinnedMessage is replaced by the row label.
- Blade renders the rows with Alpine x-for and needs Alpine.js.
