# selfstore-share
Source: https://selfstore.dev/docs/widget-share

Reference for the share panel - create view and edit links, list who has access, revoke and stop sharing, with an optional QR code and a host veto on every destructive gesture.

The panel for handing out access: create a link, see who holds one, revoke it,
stop sharing entirely.

```html
<selfstore-share id="share"></selfstore-share>
<script type="module">
  const el = document.getElementById('share');
  el.confirmAction = (a) => confirm(a.type === 'stop' ? 'Stop sharing?' : 'Revoke?');
  el.engine = myShareEngine;            // last
</script>
```

It drives a `ShareEngine` - your app's transport for links and memberships. See
[peers and groups](https://selfstore.dev/docs/peers) for what an engine is and what it must provide.

<figure class="shot">
<img class="shot__light" src="/img/widgets/share-light.webp" width="1328" height="823" loading="lazy" decoding="async" alt="The share widget, light theme" />
<img class="shot__dark" src="/img/widgets/share-dark.webp" width="1328" height="823" loading="lazy" decoding="async" alt="The share widget, dark theme" />
<figcaption>Links the app created, and who holds one. Revoking and removing run through the host veto first. Unstyled apart from the accent: this is the widget with one CSS custom property set.</figcaption>
</figure>

## Properties

| Property | Type | Default | Notes |
| --- | --- | --- | --- |
| `engine` | `ShareEngine \| null` | `null` | Your transport of links and memberships. Assign last. |
| `options` | `{ deadlineMs?: number }` | `{}` | For engines whose legs outgrow the 30s guard - a large first upload, a slow relay |
| `levels` | `ShareLevel[]` | `['read', 'write']` | Which levels the panel offers to create. Also an attribute. |
| `withCreate` | `boolean` | `true` | The create buttons. Off makes it list-and-revoke only. |
| `withMembers` | `boolean` | `true` | The members section. Off makes it links-only. |
| `confirmAction` | `(a: ShareAction) => boolean \| Promise<boolean>` | `null` | Host veto before revoke, remove or stop |
| `qrProvider` | `(url: string) => Promise<string>` | `null` | Turns a link into an image source |
| `flow` | `ShareFlow \| null` (read-only) | `null` | The underlying flow |

### `levels`

`levels` says what the panel **offers to create**. Links the engine already
lists render whatever they are, regardless of this setting - so narrowing it
never hides an existing link:

```html
<selfstore-share levels="read"></selfstore-share>
```

### `qrProvider`

The element ships no QR dependency; you inject the renderer. A data URL fits:

```ts
import QRCode from 'qrcode';
el.qrProvider = (url) => QRCode.toDataURL(url);
```

Each link card then renders it as `part="qr"`, sized with `--selfstore-qr-size`.
Without a provider, no QR is shown and nothing else changes.

## Attributes

| Attribute | Format | Sets |
| --- | --- | --- |
| `levels` | comma-separated | `levels` |
| `with-create` | `off`, `false`, `no`, `0` to disable | `withCreate` |
| `with-members` | same | `withMembers` |

## The veto

```ts
type ShareAction =
  | { type: 'revoke'; id: string }
  | { type: 'remove'; id: string }
  | { type: 'stop' };
```

Called before revoke, remove or stop runs. Answer or resolve `false` to keep
things as they are. A throwing hook reads as "no".

## Events

| Event | Detail | When |
| --- | --- | --- |
| `selfstore-link-created` | `{ link }` | A link was created |
| `selfstore-link-copied` | `{ url }` | The user copied a link |
| `selfstore-share-stopped` | none | Sharing was stopped entirely |

## Parts

Shared: `title`, `sub`, `hint`, `card`, `row`, `list`, `button`,
`button-primary`, `button-danger`, `link`, `link-danger`, `footer`,
`error-note`.

Its own: `qr` - the QR image on a link card.

## Labels

Every string is a key with a default, and the widget ships English and French. The 18 keys it owns are listed on [every label key](https://selfstore.dev/docs/widget-labels#selfstore-share); how the resolution works is on [wording](https://selfstore.dev/docs/widgets-localization).

Map of this site for a model: https://selfstore.dev/llms.txt
Every page in one file: https://selfstore.dev/llms-full.txt