@blokkli/editor 1.0.0

package/dist/runtime/components/Edit/Features/Library/LibraryDialog/index.vue

@@ -0,0 +1,184 @@
+<template>
+  <FormOverlay
+    id="library"
+    :title="$t('libraryPlaceDialogTitle', 'Add block from library')"
+    icon="reusable"
+    @close="onClose"
+  >
+    <div class="bk-library-dialog">
+      <p class="bk-lead">
+        {{
+          $t(
+            'libraryPlaceDialogLead',
+            'Select a reusable block from the library to add it to your layout. You can detach the block later.',
+          )
+        }}
+      </p>
+      <div class="bk">
+        <div class="bk-form-group">
+          <div>
+            <label class="bk-form-label" for="library_search">
+              {{ $t('libraryPlaceSearchLabel', 'Filter library items') }}
+            </label>
+            <input
+              id="library_search"
+              v-model.lazy="searchText"
+              type="text"
+              class="bk-form-input"
+              :placeholder="
+                $t('libraryPlaceSearchInputPlaceholder', 'Search library items')
+              "
+              required
+            />
+          </div>
+          <div>
+            <label class="bk-form-label" for="library_bundle">
+              {{ $t('libraryPlaceBundleSelectLabel', 'Bundle') }}
+            </label>
+            <select
+              id="library_bundle"
+              v-model="selectedBundle"
+              class="bk-form-input"
+            >
+              <option
+                v-for="v in bundleOptions"
+                :key="v.bundle"
+                :value="v.bundle"
+              >
+                {{ v.label }}
+              </option>
+            </select>
+          </div>
+        </div>
+      </div>
+      <div class="bk-library-dialog-content">
+        <Loading v-if="status === 'pending'" />
+        <ul ref="listEl" class="bk-library-dialog-list">
+          <li
+            v-for="item in items"
+            :key="item.uuid"
+            :class="{
+              'bk-is-selected': selectedItem === item.uuid,
+            }"
+            @click="selectedItem = item.uuid"
+          >
+            <LibraryListItem v-bind="item" />
+          </li>
+        </ul>
+      </div>
+    </div>
+    <div class="bk">
+      <div class="bk-pagination">
+        <button :disabled="page === 0" @click="page--">
+          <Icon name="arrow-left" />
+        </button>
+        <div>{{ page + 1 }} / {{ totalPages }}</div>
+        <button :disabled="page >= totalPages - 1" @click="page++">
+          <Icon name="arrow-right" />
+        </button>
+      </div>
+    </div>
+    <template #footer>
+      <button class="bk-button bk-is-primary" @click="onSubmit">
+        {{ $t('libraryPlaceDialogSubmit', 'Add reusable block') }}
+      </button>
+    </template>
+  </FormOverlay>
+</template>
+
+<script setup lang="ts">
+import type {
+  BlokkliAdapterGetLibraryItemsData,
+  BlokkliAdapterGetLibraryItemsResult,
+} from '#blokkli/adapter'
+import { FormOverlay, Icon } from '#blokkli/components'
+import Loading from './../../../Loading/index.vue'
+import type { BlokkliFieldElement } from '#blokkli/types'
+import { ref, useBlokkli, useAsyncData, computed, watch } from '#imports'
+import LibraryListItem from './Item/index.vue'
+
+const props = defineProps<{
+  field: BlokkliFieldElement
+}>()
+
+const { $t, adapter, types } = useBlokkli()
+
+const emit = defineEmits<{
+  (e: 'close'): void
+  (e: 'submit', uuid: string): void
+}>()
+
+const searchText = ref('')
+const selectedBundle = ref('all')
+const listEl = ref<HTMLDivElement | null>(null)
+const selectedItem = ref('')
+const page = ref(0)
+
+const allowedBundles = computed<string[]>(() => {
+  return (
+    types.getFieldConfig(
+      props.field.hostEntityType,
+      props.field.hostEntityBundle,
+      props.field.name,
+    )?.allowedBundles || []
+  ).filter((v) => {
+    return types.getBlockBundleDefinition(v)?.allowReusable
+  })
+})
+
+const onSubmit = () => {
+  if (selectedItem.value) {
+    emit('submit', selectedItem.value)
+  }
+}
+const onClose = () => {
+  emit('close')
+}
+
+const searchParams = computed<BlokkliAdapterGetLibraryItemsData>(() => {
+  return {
+    bundles:
+      selectedBundle.value !== 'all'
+        ? [selectedBundle.value]
+        : allowedBundles.value,
+    page: page.value,
+    text: searchText.value,
+  }
+})
+
+watch(searchText, function () {
+  page.value = 0
+})
+
+const { data, status } =
+  await useAsyncData<BlokkliAdapterGetLibraryItemsResult>(
+    () => adapter.getLibraryItems!(searchParams.value),
+    {
+      watch: [searchParams],
+      default: () => {
+        return {
+          items: [],
+          total: 0,
+          perPage: 50,
+        }
+      },
+    },
+  )
+
+const perPage = computed(() => data.value.perPage)
+const totalPages = computed(() => Math.ceil(data.value.total / perPage.value))
+
+const items = computed(() => data.value.items)
+
+const bundleOptions = computed(() => {
+  const bundles = allowedBundles.value.map((bundle) => {
+    const definition = types.getBlockBundleDefinition(bundle)
+    return {
+      bundle,
+      label: definition?.label || bundle,
+    }
+  })
+
+  return [{ bundle: 'all', label: $t('all', 'All') }, ...bundles]
+})
+</script>

package/dist/runtime/components/Edit/Features/Library/ReusableDialog/index.vue

@@ -0,0 +1,88 @@
+<template>
+  <DialogModal
+    :title="$t('libraryDialogTitle', 'Add to library')"
+    :lead="
+      $t(
+        'libraryDialogLead',
+        'When you add an item to the library, you can use it on multiple pages at the same time. Changes to this item are then immediately published on all pages.',
+      )
+    "
+    :width="1200"
+    icon="reusable"
+    :submit-label="$t('libraryDialogSubmit', 'Add to library')"
+    :can-submit="!!label.length"
+    @submit="$emit('confirm', label)"
+    @cancel="$emit('cancel')"
+  >
+    <div>
+      <label for="reusable_label" class="bk-form-label">{{
+        $t('libraryDialogDescriptionLabel', 'Description')
+      }}</label>
+      <input
+        id="reusable_label"
+        v-model="label"
+        type="text"
+        class="bk-form-input"
+        :placeholder="
+          $t('libraryDialogTitleInputPlaceholder', 'e.g. Teaser Campaign 2024')
+        "
+        required
+      />
+    </div>
+    <div class="bk-form-label">
+      {{ $t('libraryPreviewLabel', 'Preview') }}
+    </div>
+    <div
+      class="bk-dialog-content-element"
+      :class="[backgroundClass, { 'bk-default-bg': !backgroundClass }]"
+      :style="backgroundClass ? {} : { backgroundColor }"
+    >
+      <div ref="previewEl" />
+    </div>
+  </DialogModal>
+</template>
+
+<script lang="ts" setup>
+import { ref, useBlokkli, onMounted } from '#imports'
+
+import { DialogModal } from '#blokkli/components'
+import { realBackgroundColor } from '#blokkli/helpers'
+
+defineEmits<{
+  (e: 'confirm', label: string): void
+  (e: 'cancel'): void
+}>()
+
+const { dom, $t } = useBlokkli()
+
+const props = defineProps<{
+  uuid: string
+  backgroundClass?: string
+}>()
+
+const label = ref('')
+const width = ref(450)
+const previewEl = ref<HTMLDivElement | null>(null)
+const backgroundColor = ref('')
+
+onMounted(() => {
+  if (previewEl.value) {
+    const item = dom.findBlock(props.uuid)
+    if (!item) {
+      return
+    }
+
+    if (item.editTitle) {
+      label.value = item.editTitle.substring(0, 40)
+    }
+
+    const element = item.element()
+    const markup = dom.getDropElementMarkup(item)
+    width.value = element.getBoundingClientRect().width + 40
+    const clone = document.createElement('div')
+    clone.innerHTML = markup
+    previewEl.value.appendChild(clone)
+    backgroundColor.value = realBackgroundColor(element)
+  }
+})
+</script>

package/dist/runtime/components/Edit/Features/Library/docs.md

@@ -0,0 +1,127 @@
+The library feature provides a way to have reusable blocks that can be added to
+multiple host entities (e.g. pages).
+
+## Architecture
+
+Since a block always belongs to exactly one host entity, we cannot directly add
+the same block with the same UUID on two pages.
+
+In order to still have reusable blocks, we can instead do the following:
+
+- Define an entity type named "library_item" that is used as the host entity for
+  our reusable blocks
+- Create a block bundle named "from_library" that references a library_item
+  entity
+- Add the "from_library" block to the pages we want to display the reusable
+  block
+
+That way, when we want to add a reusable block to a page, we instead add a block
+of bundle "from_library", where we reference the library item that hosts our
+block.
+
+blökkli provides an abstraction layer to make this easier.
+
+## `from_library` block
+
+When the feature is enabled, blökkli includes a block component that handles the
+rendering of a reusable block.
+
+## Data Structure
+
+Let's see how our data structure looks like if we have a reusable block on our
+page:
+
+```typescript
+import type { FieldListItem } from '#blokkli/types'
+
+const blocks: FieldListItem[] = [
+  // Normal non-reusable block.
+  {
+    uuid: '96f7fbda-04d9-4662-9a6c-6aa3bcf964f2',
+    bundle: 'title',
+    props: {
+      title: 'Hello world',
+    },
+  },
+  // The "from_library" block.
+  {
+    uuid: '9485812c-0ecd-4699-85b2-3a031d47a0a1',
+    bundle: 'from_library',
+    // blökkli expects a single prop named libraryItem.
+    props: {
+      // The referenced library item entity.
+      libraryItem: {
+        // The actual reusable block.
+        block: {
+          uuid: '9485812c-0ecd-4699-85b2-3a031d47a0a1',
+          bundle: 'rich_text',
+          props: {
+            text: '<p>Lorem ipsum dolor sit amet</p>',
+          },
+        },
+      },
+    },
+  },
+]
+```
+
+## Rendering
+
+Rendering a reusable block results in the same DOM markup as if the block were
+placed directly, e.g. no wrapping divs.
+
+## Option inheritance
+
+The `from_library` block inherits the options defined by the reusable block it
+contains. This means the block displays the same options in the editor.
+
+When changing options on a reusable block, we store the overrides on the
+`from_library` block. This makes it possible to vary the appearance of reusable
+blocks per page.
+
+## Allowing reusable blocks
+
+Because we "wrap" the reusable block in another block, we also have to make sure
+to allow the "from_library" bundle in the fields where reusable blocks should be
+placed, in addition to allowing the bundle of the reusable block.
+
+This is done in the [getFieldConfig()](/adapter/getFieldConfig) adapter method.
+An example field config that only allows `text` blocks might look like this:
+
+```typescript
+import type { FieldConfig } from '#blokkli/types'
+
+const fieldConfig: FieldConfig[] = [
+  {
+    name: 'field_blocks',
+    entityType: 'content',
+    entityBundle: 'blog_post',
+    label: 'Blocks',
+    cardinality: -1,
+    canEdit: true,
+    allowedBundles: ['text'],
+  },
+]
+```
+
+If we allow the `text` block bundle to be made reusable, we also have to allow
+the `from_library` block bundle in our field config:
+
+```typescript
+import type { FieldConfig } from '#blokkli/types'
+
+const fieldConfig: FieldConfig[] = [
+  {
+    name: 'field_blocks',
+    entityType: 'content',
+    entityBundle: 'blog_post',
+    label: 'Blocks',
+    cardinality: -1,
+    canEdit: true,
+    allowedBundles: ['text', 'from_library'],
+  },
+]
+```
+
+Basically: blökkli checks **both** bundles in the field config. This structure
+allows us to also restrict placement of reusable blocks.

package/dist/runtime/components/Edit/Features/Library/index.vue

@@ -0,0 +1,184 @@
+<template>
+  <PluginItemAction
+    v-if="isReusable"
+    id="library_detach"
+    :title="$t('libraryDetach', 'Detach from library')"
+    icon="detach"
+    multiple
+    :weight="-70"
+    @click="onDetach"
+  />
+  <PluginItemAction
+    v-else-if="!isReusable"
+    id="library_make_reusable"
+    :title="$t('libraryAdd', 'Add to library')"
+    :disabled="!canMakeReusable || state.editMode.value !== 'editing'"
+    icon="reusable"
+    :weight="-70"
+    @click="showReusableDialog = true"
+  />
+
+  <PluginAddAction
+    v-if="
+      adapter.addLibraryItem && adapter.getLibraryItems && isSupportedOnEntity
+    "
+    type="library"
+    :title="$t('libraryAddFromLibrary', 'Add from library')"
+    :description="
+      $t(
+        'libraryAddDescription',
+        'Add a reusable block from the block library.',
+      )
+    "
+    icon="reusable"
+    color="lime"
+    item-bundle="from_library"
+    :disabled="!fromLibraryAllowedInList"
+    @placed="placedAction = $event"
+  />
+
+  <Teleport to="body">
+    <transition appear name="bk-slide-up" :duration="300">
+      <ReusableDialog
+        v-if="showReusableDialog && selectedItem"
+        :uuid="selectedItem.uuid"
+        :background-class="definition?.editor?.previewBackgroundClass"
+        @confirm="onMakeReusable"
+        @cancel="showReusableDialog = false"
+      />
+    </transition>
+  </Teleport>
+
+  <Teleport to="body">
+    <transition name="bk-slide-in" :duration="200">
+      <LibraryDialog
+        v-if="placedAction && adapter.getLibraryItems"
+        :field="placedAction.field"
+        @close="placedAction = null"
+        @submit="onAddLibraryItem"
+      />
+    </transition>
+  </Teleport>
+</template>
+
+<script lang="ts" setup>
+import { ref, computed, useBlokkli, defineBlokkliFeature } from '#imports'
+import { PluginItemAction, PluginAddAction } from '#blokkli/plugins'
+import ReusableDialog from './ReusableDialog/index.vue'
+import LibraryDialog from './LibraryDialog/index.vue'
+import { getDefinition } from '#blokkli/definitions'
+import type { ActionPlacedEvent } from '#blokkli/types'
+
+const { adapter } = defineBlokkliFeature({
+  id: 'library',
+  icon: 'reusable',
+  label: 'Library',
+  description:
+    'Implements support for a block library to manage reusable blocks.',
+  requiredAdapterMethods: ['makeBlockReusable', 'detachReusableBlock'],
+})
+
+const { selection, state, types, $t, eventBus } = useBlokkli()
+const showReusableDialog = ref(false)
+
+const selectedItem = computed(() => {
+  if (selection.blocks.value.length !== 1) {
+    return
+  }
+
+  return selection.blocks.value[0]
+})
+
+const onDetach = async () => {
+  if (!adapter.detachReusableBlock || !selection.uuids.value.length) {
+    return
+  }
+  await state.mutateWithLoadingState(() =>
+    adapter.detachReusableBlock({
+      uuids: selection.uuids.value,
+    }),
+  )
+
+  eventBus.emit('select:end')
+}
+
+const placedAction = ref<ActionPlacedEvent | null>(null)
+const onAddLibraryItem = async (uuid: string) => {
+  if (!placedAction.value || !adapter.addLibraryItem) {
+    return
+  }
+
+  await state.mutateWithLoadingState(() =>
+    adapter.addLibraryItem({
+      libraryItemUuid: uuid,
+      host: placedAction.value!.host,
+      afterUuid: placedAction.value!.preceedingUuid,
+    }),
+  )
+  placedAction.value = null
+}
+
+const definition = computed(() =>
+  selectedItem?.value
+    ? getDefinition(
+        selectedItem.value.itemBundle,
+        selectedItem.value.hostFieldListType,
+        selectedItem.value.parentBlockBundle,
+      )
+    : null,
+)
+
+const itemBundle = computed(() =>
+  selectedItem?.value
+    ? types.getBlockBundleDefinition(selectedItem.value.itemBundle)
+    : null,
+)
+
+const isReusable = computed(
+  () =>
+    selection.blocks.value.length &&
+    selection.blocks.value.every((v) => v.itemBundle === 'from_library'),
+)
+
+async function onMakeReusable(label: string) {
+  showReusableDialog.value = false
+  if (!selectedItem?.value?.uuid) {
+    return
+  }
+  await state.mutateWithLoadingState(
+    () =>
+      adapter.makeBlockReusable({
+        label,
+        uuid: selectedItem.value!.uuid,
+      }),
+    $t('libraryError', 'Failed to add block to library.'),
+  )
+  eventBus.emit('select:end')
+}
+
+const isSupportedOnEntity = computed(() =>
+  types.generallyAvailableBundles.find((v) => v.id === 'from_library'),
+)
+
+const fromLibraryAllowedInList = computed(() => {
+  if (!selection.uuids.value.length) {
+    return !!types.generallyAvailableBundles.find(
+      (v) => v.id === 'from_library',
+    )
+  }
+  return types.allowedTypesInList.value.includes('from_library')
+})
+
+const canMakeReusable = computed(
+  () =>
+    !isReusable.value &&
+    itemBundle?.value?.allowReusable &&
+    fromLibraryAllowedInList.value,
+)
+</script>
+
+<script lang="ts">
+export default {
+  name: 'Library',
+}
+</script>