@docsector/docsector-reader 3.4.0 → 3.6.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/pages/manual/content/blocks/cards.overview.en-US.md

@@ -0,0 +1,32 @@
+## Overview
+
+Cards render a responsive grid of linked content blocks directly inside Markdown.
+
+They are useful for landing sections, curated resource lists, and any place where a plain list of links feels too flat.
+
+## Markdown Syntax
+
+```html
+<d-block-cards title="Explore more">
+  <d-block-card
+    title="Install"
+    description="Set up the project"
+    to="/guide/getting-started"
+    image="/images/cards/getting-started-cover.svg"
+  />
+  <d-block-card
+    title="GitHub"
+    description="Open the repository"
+    href="https://github.com/docsector/docsector-reader"
+    icon="launch"
+  />
+</d-block-cards>
+```
+
+## Notes
+
+- Use `to` for internal navigation and `href` for external URLs.
+- Add `image` when the card should feel more like a landing-page tile.
+- Add `icon` when the card has no image but still needs a stronger visual cue.
+- Short descriptions scan better than paragraph-sized copy.
+- Cover images look best in a wide format such as 16:9.

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

@@ -0,0 +1,32 @@
+## Visão geral
+
+Cards renderizam uma grade responsiva de blocos com link diretamente dentro do Markdown.
+
+Eles são úteis para seções de entrada, listas curadas de recursos e qualquer lugar em que uma lista simples de links fique visualmente pobre.
+
+## Sintaxe Markdown
+
+```html
+<d-block-cards title="Explore mais">
+  <d-block-card
+    title="Instalação"
+    description="Configure o projeto"
+    to="/guide/getting-started"
+    image="/images/cards/getting-started-cover.svg"
+  />
+  <d-block-card
+    title="GitHub"
+    description="Abra o repositório"
+    href="https://github.com/docsector/docsector-reader"
+    icon="launch"
+  />
+</d-block-cards>
+```
+
+## Notas
+
+- Use `to` para navegação interna e `href` para URLs externas.
+- Adicione `image` quando o card precisar se comportar mais como um bloco de landing page.
+- Adicione `icon` quando o card não tiver imagem, mas ainda precisar de uma pista visual mais forte.
+- Descrições curtas funcionam melhor do que textos longos.
+- Imagens de capa ficam melhores em formatos largos, como 16:9.

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

@@ -0,0 +1,39 @@
+## Showcase
+
+<d-block-cards title="Start here">
+  <d-block-card
+    title="Getting Started"
+    description="Install and run the project"
+    to="/guide/getting-started"
+    image="/images/cards/getting-started-cover.svg"
+  />
+  <d-block-card
+    title="Quick Links"
+    description="Open another navigation-focused block"
+    to="/manual/content/blocks/quick-links"
+    image="/images/cards/quick-links-cover.svg"
+  />
+  <d-block-card
+    title="GitHub"
+    description="Open the repository"
+    href="https://github.com/docsector/docsector-reader"
+    icon="launch"
+  />
+</d-block-cards>
+
+## Without Cover Images
+
+<d-block-cards title="Continue reading">
+  <d-block-card
+    title="Expandable"
+    description="Read the collapsible content block overview"
+    to="/manual/content/blocks/expandable"
+    icon="unfold_more"
+  />
+  <d-block-card
+    title="Page structure"
+    description="Review the main page container structure"
+    to="/manual/content/structures/page"
+    icon="view_quilt"
+  />
+</d-block-cards>

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

@@ -0,0 +1,39 @@
+## Showcase
+
+<d-block-cards title="Comece por aqui">
+  <d-block-card
+    title="Primeiros passos"
+    description="Instale e execute o projeto"
+    to="/guide/getting-started"
+    image="/images/cards/getting-started-cover.svg"
+  />
+  <d-block-card
+    title="Quick Links"
+    description="Abra outro block focado em navegação"
+    to="/manual/content/blocks/quick-links"
+    image="/images/cards/quick-links-cover.svg"
+  />
+  <d-block-card
+    title="GitHub"
+    description="Abra o repositório"
+    href="https://github.com/docsector/docsector-reader"
+    icon="launch"
+  />
+</d-block-cards>
+
+## Sem imagens de capa
+
+<d-block-cards title="Continue lendo">
+  <d-block-card
+    title="Expandable"
+    description="Leia a visão geral do block colapsável"
+    to="/manual/content/blocks/expandable"
+    icon="unfold_more"
+  />
+  <d-block-card
+    title="Estrutura de página"
+    description="Revise a estrutura principal do container de página"
+    to="/manual/content/structures/page"
+    icon="view_quilt"
+  />
+</d-block-cards>

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.index.js

@@ -599,6 +599,34 @@ export default {
     }
   },
 
+  '/content/blocks/embedded-urls': {
+    config: {
+      icon: 'link',
+      status: 'new',
+      meta: {
+        description: {
+          'en-US': 'Embedded URLs — Documentation of Docsector Reader',
+          'pt-BR': 'URLs embutidas — Documentação do Docsector Reader'
+        }
+      },
+      book: 'manual',
+      menu: {},
+      subpages: {
+        showcase: true
+      }
+    },
+    data: {
+      'en-US': { title: 'Embedded URLs' },
+      'pt-BR': { title: 'URLs embutidas' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'embed embedded url youtube vimeo spotify codepen iframe preview external link gitbook',
+        'pt-BR': 'embed url embutida youtube vimeo spotify codepen iframe preview link externo gitbook'
+      }
+    }
+  },
+
   '/content/blocks/math-and-tex': {
     config: {
       icon: 'functions',
@@ -739,6 +767,34 @@ export default {
     }
   },
 
+  '/content/blocks/cards': {
+    config: {
+      icon: 'view_module',
+      status: 'done',
+      meta: {
+        description: {
+          'en-US': 'Cards — Documentation of Docsector Reader',
+          'pt-BR': 'Cartões — Documentacao do Docsector Reader'
+        }
+      },
+      book: 'manual',
+      menu: {},
+      subpages: {
+        showcase: true
+      }
+    },
+    data: {
+      'en-US': { title: 'Cards' },
+      'pt-BR': { title: 'Cartões' }
+    },
+    metadata: {
+      tags: {
+        'en-US': 'cards grid cover image navigation content links layout',
+        'pt-BR': 'cartões grade imagem capa navegação conteúdo links layout'
+      }
+    }
+  },
+
   '/content/structures': {
     config: null,
     data: {