@docsector/docsector-reader 3.3.1 → 3.5.0

package/src/composables/useEmbeddedUrl.js

@@ -0,0 +1,365 @@
+const DEFAULT_EMBED = {
+  mode: 'link',
+  provider: 'link',
+  kind: 'link',
+  icon: 'link',
+  title: '',
+  providerLabel: '',
+  canonicalUrl: '',
+  displayUrl: '',
+  embedSrc: '',
+  aspectRatio: '',
+  frameHeight: 0,
+  allow: '',
+  allowFullscreen: false
+}
+
+const YOUTUBE_HOSTS = new Set([
+  'youtu.be',
+  'youtube.com',
+  'www.youtube.com',
+  'm.youtube.com',
+  'music.youtube.com',
+  'youtube-nocookie.com',
+  'www.youtube-nocookie.com'
+])
+
+const VIMEO_HOSTS = new Set([
+  'vimeo.com',
+  'www.vimeo.com',
+  'player.vimeo.com'
+])
+
+const SPOTIFY_HOSTS = new Set([
+  'spotify.com',
+  'www.spotify.com',
+  'open.spotify.com'
+])
+
+const CODEPEN_HOSTS = new Set([
+  'codepen.io',
+  'www.codepen.io'
+])
+
+const SPOTIFY_PROVIDER_BY_KIND = {
+  track: {
+    kind: 'audio',
+    icon: 'music_note',
+    title: 'Spotify track',
+    frameHeight: 152
+  },
+  episode: {
+    kind: 'audio',
+    icon: 'podcasts',
+    title: 'Spotify episode',
+    frameHeight: 232
+  },
+  artist: {
+    kind: 'music',
+    icon: 'person',
+    title: 'Spotify artist',
+    frameHeight: 352
+  },
+  album: {
+    kind: 'music',
+    icon: 'album',
+    title: 'Spotify album',
+    frameHeight: 352
+  },
+  playlist: {
+    kind: 'music',
+    icon: 'queue_music',
+    title: 'Spotify playlist',
+    frameHeight: 352
+  },
+  show: {
+    kind: 'podcast',
+    icon: 'radio',
+    title: 'Spotify show',
+    frameHeight: 352
+  }
+}
+
+const createFallbackResult = (rawUrl = '', title = '') => {
+  const trimmed = String(rawUrl || '').trim()
+  const normalized = parseHttpUrl(trimmed)
+
+  return {
+    ...DEFAULT_EMBED,
+    title: title || normalized?.hostname || trimmed,
+    providerLabel: normalized?.hostname || '',
+    canonicalUrl: normalized?.toString() || trimmed,
+    displayUrl: normalized?.toString() || trimmed
+  }
+}
+
+const parseHttpUrl = (rawUrl = '') => {
+  const trimmed = String(rawUrl || '').trim()
+
+  if (!trimmed) {
+    return null
+  }
+
+  try {
+    const url = new URL(trimmed)
+
+    if (!['http:', 'https:'].includes(url.protocol)) {
+      return null
+    }
+
+    return url
+  } catch {
+    return null
+  }
+}
+
+const mergeSearchParams = (url, options = {}) => {
+  const params = new URLSearchParams(url.search)
+
+  ;(options.remove || []).forEach((key) => {
+    params.delete(key)
+  })
+
+  Object.entries(options.set || {}).forEach(([key, value]) => {
+    if (value === '' || value === null || value === undefined) {
+      params.delete(key)
+      return
+    }
+
+    params.set(key, String(value))
+  })
+
+  const query = params.toString()
+  return query ? `?${query}` : ''
+}
+
+const parseTimeToSeconds = (value = '') => {
+  const trimmed = String(value || '').trim()
+
+  if (!trimmed) {
+    return ''
+  }
+
+  if (/^\d+$/.test(trimmed)) {
+    return trimmed
+  }
+
+  const match = trimmed.match(/^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/i)
+  if (!match) {
+    return ''
+  }
+
+  const hours = Number(match[1] || 0)
+  const minutes = Number(match[2] || 0)
+  const seconds = Number(match[3] || 0)
+  const total = (hours * 3600) + (minutes * 60) + seconds
+
+  return total > 0 ? String(total) : ''
+}
+
+const resolveYouTubeVideoId = (url) => {
+  const segments = url.pathname.split('/').filter(Boolean)
+
+  if (url.hostname === 'youtu.be') {
+    return segments[0] || ''
+  }
+
+  if (segments[0] === 'watch') {
+    return url.searchParams.get('v') || ''
+  }
+
+  if (['embed', 'shorts', 'live', 'v'].includes(segments[0])) {
+    return segments[1] || ''
+  }
+
+  return url.searchParams.get('v') || ''
+}
+
+const resolveYouTubeEmbed = (url, title = '') => {
+  const videoId = resolveYouTubeVideoId(url)
+
+  if (!videoId) {
+    return null
+  }
+
+  const start = parseTimeToSeconds(url.searchParams.get('t'))
+  const query = mergeSearchParams(url, {
+    remove: ['v', 't'],
+    set: {
+      ...(start ? { start } : {}),
+      ...((url.searchParams.get('loop') === '1' || url.searchParams.get('loop') === 'true') && !url.searchParams.get('playlist')
+        ? { playlist: videoId }
+        : {})
+    }
+  })
+
+  return {
+    ...DEFAULT_EMBED,
+    mode: 'embed',
+    provider: 'youtube',
+    kind: 'video',
+    icon: 'smart_display',
+    title: title || 'YouTube video',
+    providerLabel: 'YouTube',
+    canonicalUrl: url.toString(),
+    displayUrl: url.toString(),
+    embedSrc: `https://www.youtube.com/embed/${videoId}${query}`,
+    aspectRatio: '16 / 9',
+    allow: 'accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share',
+    allowFullscreen: true
+  }
+}
+
+const resolveVimeoVideoId = (url) => {
+  const segments = url.pathname.split('/').filter(Boolean)
+
+  if (segments[0] === 'video') {
+    return segments[1] || ''
+  }
+
+  return segments.find((segment) => /^\d+$/.test(segment)) || ''
+}
+
+const resolveVimeoEmbed = (url, title = '') => {
+  const videoId = resolveVimeoVideoId(url)
+
+  if (!videoId) {
+    return null
+  }
+
+  return {
+    ...DEFAULT_EMBED,
+    mode: 'embed',
+    provider: 'vimeo',
+    kind: 'video',
+    icon: 'movie',
+    title: title || 'Vimeo video',
+    providerLabel: 'Vimeo',
+    canonicalUrl: url.toString(),
+    displayUrl: url.toString(),
+    embedSrc: `https://player.vimeo.com/video/${videoId}${mergeSearchParams(url)}`,
+    aspectRatio: '16 / 9',
+    allow: 'autoplay; fullscreen; picture-in-picture',
+    allowFullscreen: true
+  }
+}
+
+const resolveSpotifyParts = (url) => {
+  const segments = url.pathname.split('/').filter(Boolean)
+  const embedIndex = segments[0] === 'embed' ? 1 : 0
+  const type = segments[embedIndex] || ''
+  const id = segments[embedIndex + 1] || ''
+
+  if (!SPOTIFY_PROVIDER_BY_KIND[type] || !id) {
+    return null
+  }
+
+  return { type, id }
+}
+
+const resolveSpotifyEmbed = (url, title = '') => {
+  const parts = resolveSpotifyParts(url)
+
+  if (parts === null) {
+    return null
+  }
+
+  const definition = SPOTIFY_PROVIDER_BY_KIND[parts.type]
+
+  return {
+    ...DEFAULT_EMBED,
+    mode: 'embed',
+    provider: 'spotify',
+    kind: definition.kind,
+    icon: definition.icon,
+    title: title || definition.title,
+    providerLabel: 'Spotify',
+    canonicalUrl: url.toString(),
+    displayUrl: url.toString(),
+    embedSrc: `https://open.spotify.com/embed/${parts.type}/${parts.id}${mergeSearchParams(url)}`,
+    aspectRatio: '',
+    frameHeight: definition.frameHeight,
+    allow: 'autoplay; clipboard-write; encrypted-media; fullscreen; picture-in-picture',
+    allowFullscreen: false
+  }
+}
+
+const resolveCodePenParts = (url) => {
+  const segments = url.pathname.split('/').filter(Boolean)
+
+  if (segments[0] === 'team') {
+    const team = segments[1] || ''
+    const penType = segments[2] || ''
+    const penId = segments[3] || ''
+
+    if (!team || !penId || !['pen', 'full', 'details', 'embed', 'debug'].includes(penType)) {
+      return null
+    }
+
+    return {
+      user: `team/${team}`,
+      penId
+    }
+  }
+
+  const user = segments[0] || ''
+  const penType = segments[1] || ''
+  const penId = segments[2] || ''
+
+  if (!user || !penId || !['pen', 'full', 'details', 'embed', 'debug'].includes(penType)) {
+    return null
+  }
+
+  return { user, penId }
+}
+
+const resolveCodePenEmbed = (url, title = '') => {
+  const parts = resolveCodePenParts(url)
+
+  if (parts === null) {
+    return null
+  }
+
+  return {
+    ...DEFAULT_EMBED,
+    mode: 'embed',
+    provider: 'codepen',
+    kind: 'code',
+    icon: 'code',
+    title: title || 'CodePen embed',
+    providerLabel: 'CodePen',
+    canonicalUrl: url.toString(),
+    displayUrl: url.toString(),
+    embedSrc: `https://codepen.io/${parts.user}/embed/${parts.penId}${mergeSearchParams(url)}`,
+    aspectRatio: '16 / 9',
+    allow: 'accelerometer; camera; clipboard-write; display-capture; encrypted-media; geolocation; gyroscope; microphone; midi; web-share',
+    allowFullscreen: true
+  }
+}
+
+export const resolveEmbeddedUrl = (rawUrl = '', options = {}) => {
+  const title = String(options.title || '').trim()
+  const normalized = parseHttpUrl(rawUrl)
+
+  if (normalized === null) {
+    return createFallbackResult(rawUrl, title)
+  }
+
+  if (YOUTUBE_HOSTS.has(normalized.hostname)) {
+    return resolveYouTubeEmbed(normalized, title) || createFallbackResult(rawUrl, title)
+  }
+
+  if (VIMEO_HOSTS.has(normalized.hostname)) {
+    return resolveVimeoEmbed(normalized, title) || createFallbackResult(rawUrl, title)
+  }
+
+  if (SPOTIFY_HOSTS.has(normalized.hostname)) {
+    return resolveSpotifyEmbed(normalized, title) || createFallbackResult(rawUrl, title)
+  }
+
+  if (CODEPEN_HOSTS.has(normalized.hostname)) {
+    return resolveCodePenEmbed(normalized, title) || createFallbackResult(rawUrl, title)
+  }
+
+  return createFallbackResult(rawUrl, title)
+}

package/src/css/app.sass

@@ -15,6 +15,11 @@ body
 body.body--light
   --q-primary: #655529 !important
   --q-secondary: #000080 !important
+  --task-list-checkbox-bg: #ffffff
+  --task-list-checkbox-border: #7c6a3a
+  --task-list-checkbox-checked-bg: #5e4c1f
+  --task-list-checkbox-checked-border: #4f3f18
+  --task-list-checkbox-check: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='none' stroke='%23ffffff' stroke-linecap='round' stroke-linejoin='round' stroke-width='2.3' d='M3.25 8.5 6.4 11.4 12.75 4.9'/%3E%3C/svg%3E")
 
   --q-primary-background: #FFF !important
 
@@ -48,6 +53,11 @@ body.body--dark
   --q-primary-in-dark-bg: #C1A667 !important
   --q-secondary: #FFA07A !important
   --q-negative: #fc001b !important
+  --task-list-checkbox-bg: #181818
+  --task-list-checkbox-border: #8f8a78
+  --task-list-checkbox-checked-bg: #d3b874
+  --task-list-checkbox-checked-border: #ebd08a
+  --task-list-checkbox-check: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath fill='none' stroke='%23151515' stroke-linecap='round' stroke-linejoin='round' stroke-width='2.3' d='M3.25 8.5 6.4 11.4 12.75 4.9'/%3E%3C/svg%3E")
 
   --q-light-in-dark-1: #ababab
   --q-light-in-dark-2: #c9c9c9
@@ -199,6 +209,39 @@ body.body--dark
     overflow-y: hidden
     padding: 0.35rem 0.1rem
 
+  ul.contains-task-list,
+  ol.contains-task-list
+    list-style: none
+    padding-left: 1.75rem
+
+  li.task-list-item
+    list-style: none
+
+  input.task-list-item-checkbox
+    appearance: none
+    -webkit-appearance: none
+    width: 1rem
+    height: 1rem
+    margin: 0 0.55rem 0 -1.45rem
+    vertical-align: middle
+    pointer-events: none
+    opacity: 1
+    border: 2px solid var(--task-list-checkbox-border)
+    border-radius: 0.2rem
+    background-color: var(--task-list-checkbox-bg)
+    background-position: center
+    background-repeat: no-repeat
+    background-size: 0.72rem 0.72rem
+    box-shadow: 0 0 0 1px rgba(0, 0, 0, 0.08)
+
+    &:checked
+      background-color: var(--task-list-checkbox-checked-bg)
+      border-color: var(--task-list-checkbox-checked-border)
+      background-image: var(--task-list-checkbox-check)
+
+    &:disabled
+      opacity: 1
+
   a
     text-decoration: none
     outline: 0

package/src/pages/manual/content/blocks/embedded-urls.overview.en-US.md

@@ -0,0 +1,33 @@
+## Overview
+
+Embedded URLs turn supported public links into responsive embeds directly inside Markdown pages.
+
+This block is a higher-level alternative to raw iframe markup when the source is a supported provider and the page should keep a consistent card + preview treatment.
+
+## Markdown Syntax
+
+```html
+<d-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE" title="YouTube player demo">
+Optional caption rendered as inline Markdown.
+</d-embedded-url>
+```
+
+You can also omit the caption body when the provider preview already gives enough context:
+
+```html
+<d-embedded-url url="https://open.spotify.com/track/7ouMYWpwJ422jRcDASZB7P" />
+```
+
+## Supported Providers
+
+- YouTube
+- Vimeo
+- Spotify
+- CodePen
+
+## Notes
+
+- `url` is required. `title` is optional.
+- The block preserves the original query string, so provider options such as `autoplay=1&loop=1` continue to work when the provider supports them.
+- Unsupported or private URLs fall back to a safe external-link card instead of attempting a generic iframe.
+- Use Raw HTML when you need a provider outside the curated list or when you need full manual iframe control.

package/src/pages/manual/content/blocks/embedded-urls.overview.pt-BR.md

@@ -0,0 +1,33 @@
+## Apresentação
+
+URLs embutidas transformam links públicos suportados em embeds responsivos diretamente dentro das páginas Markdown.
+
+Este block é uma alternativa de nível mais alto ao uso manual de iframe quando a origem pertence a um provider suportado e a página deve manter um tratamento consistente de preview + card.
+
+## Sintaxe Markdown
+
+```html
+<d-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE" title="Demo do player do YouTube">
+Legenda opcional renderizada como Markdown inline.
+</d-embedded-url>
+```
+
+Você também pode omitir o corpo quando o preview do provider já entrega contexto suficiente:
+
+```html
+<d-embedded-url url="https://open.spotify.com/track/7ouMYWpwJ422jRcDASZB7P" />
+```
+
+## Providers suportados
+
+- YouTube
+- Vimeo
+- Spotify
+- CodePen
+
+## Observações
+
+- `url` é obrigatório. `title` é opcional.
+- O block preserva a query string original, então opções do provider como `autoplay=1&loop=1` continuam funcionando quando houver suporte.
+- URLs não suportadas ou privadas fazem fallback para um card seguro com link externo, sem tentar um iframe genérico.
+- Use HTML bruto quando você precisar de um provider fora da lista curada ou de controle manual total sobre o iframe.

package/src/pages/manual/content/blocks/embedded-urls.showcase.en-US.md

@@ -0,0 +1,25 @@
+## Showcase
+
+### YouTube Video
+
+<d-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE&autoplay=1&loop=1" title="YouTube player demo">
+The original playback query parameters stay attached to the provider URL.
+</d-embedded-url>
+
+### Spotify Track
+
+<d-embedded-url url="https://open.spotify.com/track/7ouMYWpwJ422jRcDASZB7P?si=1234">
+Spotify links render with the provider-specific compact player height.
+</d-embedded-url>
+
+### CodePen Demo
+
+<d-embedded-url url="https://codepen.io/team/codepen/pen/PNaGbb?default-tab=result" title="Interactive demo">
+Use the same block for live front-end demos without dropping to raw HTML.
+</d-embedded-url>
+
+### Unsupported URL Fallback
+
+<d-embedded-url url="https://example.com/docs/embed-me" title="External API docs">
+Unsupported providers render a safe link card so the reading flow still keeps the URL visible and actionable.
+</d-embedded-url>

package/src/pages/manual/content/blocks/embedded-urls.showcase.pt-BR.md

@@ -0,0 +1,25 @@
+## Demonstração
+
+### Vídeo do YouTube
+
+<d-embedded-url url="https://www.youtube.com/watch?v=M7lc1UVf-VE&autoplay=1&loop=1" title="Demo do player do YouTube">
+Os parâmetros originais de reprodução continuam anexados à URL do provider.
+</d-embedded-url>
+
+### Faixa do Spotify
+
+<d-embedded-url url="https://open.spotify.com/track/7ouMYWpwJ422jRcDASZB7P?si=1234">
+Links do Spotify renderizam com a altura compacta específica do provider.
+</d-embedded-url>
+
+### Demo no CodePen
+
+<d-embedded-url url="https://codepen.io/team/codepen/pen/PNaGbb?default-tab=result" title="Demo interativa">
+Use o mesmo block para demos front-end ao vivo sem cair para HTML bruto.
+</d-embedded-url>
+
+### Fallback para URL não suportada
+
+<d-embedded-url url="https://example.com/docs/embed-me" title="Documentação externa da API">
+Providers não suportados renderizam um card seguro com link externo, mantendo a URL visível e acionável no fluxo de leitura.
+</d-embedded-url>

package/src/pages/manual/content/blocks/task-lists.overview.en-US.md

@@ -0,0 +1,20 @@
+## Overview
+
+Use task lists when each item should carry an explicit done or not-done state.
+
+They work well for release preparation, editorial queues, migration follow-ups, and any checklist where progress matters as much as the content itself.
+
+## Markdown Syntax
+
+```markdown
+- [ ] Write the overview page
+- [x] Add localized examples
+  - [ ] Review screenshots
+  - [x] Update internal links
+```
+
+## Notes
+
+- Task lists follow the same indentation rules as regular Markdown lists.
+- Use `[ ]` for pending items and `[x]` for completed items.
+- Published readers see static checkboxes and cannot toggle them from the page.

package/src/pages/manual/content/blocks/task-lists.overview.pt-BR.md

@@ -0,0 +1,20 @@
+## Visão Geral
+
+Use listas de tarefas quando cada item precisar deixar explícito se foi concluído ou não.
+
+Elas funcionam bem para preparação de releases, filas editoriais, acompanhamentos de migração e qualquer checklist em que o progresso importa tanto quanto o conteúdo.
+
+## Sintaxe em Markdown
+
+```markdown
+- [ ] Escreva a página de visão geral
+- [x] Adicione exemplos localizados
+  - [ ] Revise as capturas de tela
+  - [x] Atualize os links internos
+```
+
+## Observações
+
+- Listas de tarefas seguem as mesmas regras de indentação das listas Markdown comuns.
+- Use `[ ]` para itens pendentes e `[x]` para itens concluídos.
+- Leitores da documentação publicada veem checkboxes estáticos e não podem alterná-los pela página.

package/src/pages/manual/content/blocks/task-lists.showcase.en-US.md

@@ -0,0 +1,23 @@
+## Showcase
+
+### Simple Tasks
+
+- [ ] Write the overview page
+- [x] Add the showcase page
+- [ ] Review internal links
+
+### Nested Tasks
+
+- [ ] Prepare the release
+  - [x] Update the changelog
+  - [ ] Run smoke tests
+  - [ ] Publish the package
+
+### Mixed Guidance
+
+> [!NOTE]
+> Readers can see the authored state of each task, but published checkboxes stay read-only.
+
+- [x] Keep completed items checked in the source.
+- [ ] Use task lists when the state matters more than the order.
+- Regular bullet lists are still better for collections that do not need a done/not-done signal.

package/src/pages/manual/content/blocks/task-lists.showcase.pt-BR.md

@@ -0,0 +1,23 @@
+## Showcase
+
+### Tarefas Simples
+
+- [ ] Escreva a página de visão geral
+- [x] Adicione a página de showcase
+- [ ] Revise os links internos
+
+### Tarefas Aninhadas
+
+- [ ] Prepare a release
+  - [x] Atualize o changelog
+  - [ ] Execute smoke tests
+  - [ ] Publique o pacote
+
+### Orientação de Uso
+
+> [!NOTE]
+> Leitores conseguem ver o estado definido no Markdown, mas os checkboxes publicados continuam somente leitura.
+
+- [x] Mantenha marcados os itens concluídos no conteúdo-fonte.
+- [ ] Use listas de tarefas quando o estado importar mais do que a ordem.
+- Listas com marcadores continuam melhores para coleções que não precisam de sinal de concluído ou pendente.