Skip to content

Commit

Permalink
docs: wording
Browse files Browse the repository at this point in the history
  • Loading branch information
lihbr committed Dec 12, 2024
1 parent 16044fd commit 55ee4c7
Show file tree
Hide file tree
Showing 9 changed files with 26 additions and 26 deletions.
10 changes: 5 additions & 5 deletions messages/alt-must-be-an-empty-string.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,24 +5,24 @@
Both `alt` and `fallbackAlt` can only be used to [declare an image as decorative][mdn-alt-decorative-image] by pasing an empty string. You may not pass arbitrary alternative text to the `alt` prop.

```html
<!-- Will render `alt` using the Image field's `alt` property. -->
<!-- Will render `alt` using the image field's `alt` property. -->
<PrismicImage :field="doc.data.imageField" />

<!-- Will always render `alt=""`. -->
<PrismicImage :field="doc.data.imageField" alt="" />

<!-- Will render `alt=""` only if the Image field's alt property is empty. -->
<!-- Will render `alt=""` only if the image field's alt property is empty. -->
<PrismicImage :field="doc.data.imageField" fallbackAlt="" />
```

All images should have an alt value. `<PrismicImage>` will automatically use the Image field's `alt` property written in the Prismic Editor. If the Image field's `alt` property is empty, the `alt` HTML attribute will not be included _unless_ one of `alt` or `fallbackAlt` is used.
All images should have an alt value. `<PrismicImage>` will automatically use the image field's `alt` property written in the Prismic Editor. If the image field's `alt` property is empty, the `alt` HTML attribute will not be included _unless_ one of `alt` or `fallbackAlt` is used.

For more details on decorative images, [see the MDN article on the `<img>` HTML element's `alt` attribute][mdn-alt-decorative-image].

## Deciding between `alt=""` and `fallbackAlt=""`

`alt=""` will always mark the image as decorative, ignoring the provied Image field's `alt` property. Use this when the image is always used for decorative or presentational purposes.
`alt=""` will always mark the image as decorative, ignoring the provied image field's `alt` property. Use this when the image is always used for decorative or presentational purposes.

`fallbackAlt=""` will only mark the image as decorative if the provided Image field's `alt` property is empty. Use this when you want to mark the image as decorative _unless_ alternative text is provided in the Prismic Editor. **Generally speaking, this is discouraged**; prefer marking the image as decorative intentionally.
`fallbackAlt=""` will only mark the image as decorative if the provided image field's `alt` property is empty. Use this when you want to mark the image as decorative _unless_ alternative text is provided in the Prismic Editor. **Generally speaking, this is discouraged**; prefer marking the image as decorative intentionally.

[mdn-alt-decorative-image]: https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt#decorative_images
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ The above snippet relies on an `Heading2.vue` component. Here's an example of th

```html
<script setup>
import { getSliceComponentProps } from "@prismicio/vue"
import { getRichTextComponentProps } from "@prismicio/vue"
defineProps(getRichTextComponentProps())
</script>
Expand All @@ -45,7 +45,7 @@ defineProps(getRichTextComponentProps())
</template>
```

Learn more about the new component serializer on [`@prismicio/vue` technical references][prismic-vue-rich-text].
Learn more about the new component serializer on the [`@prismicio/vue` technical reference][prismic-vue-rich-text].

[prismic-vue]: https://prismic.io/docs/technical-reference/prismicio-vue
[prismic-vue-rich-text]: https://prismic.io/docs/technical-reference/prismicio-vue#prismicrichtext
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
# `<PrismicText>` works only with Rich Text and Title fields
# `<PrismicText>` works only with Rich Text and title fields

`<PrismicText>` works only with [Rich Text and Title fields][rich-text-title-field]. It renders the field's value as plain text (i.e. with no formatting, paragraphs, or headings).
`<PrismicText>` works only with [Rich Text and title fields][rich-text-title-field]. It renders the field's value as plain text (i.e. with no formatting, paragraphs, or headings).

```html
<!-- Will render a plain text version of the Rich Text field's value. -->
<!-- Will render a plain text version of the rich text field's value. -->
<PrismicText :field="doc.data.richTextField" />
```

Expand Down
10 changes: 5 additions & 5 deletions src/PrismicImage.vue
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ import { usePrismic } from "./usePrismic"
*/
export type PrismicImageProps = {
/**
* The Prismic Image field or thumbnail to render.
* The Prismic image field or thumbnail to render.
*/
field: ImageField | ImageField<string>
Expand All @@ -37,7 +37,7 @@ export type PrismicImageProps = {
alt?: ""
/**
* Declare an image as decorative only if the Image field does not have
* Declare an image as decorative only if the image field does not have
* alternative text by providing `fallbackAlt=""`.
*
* See:
Expand All @@ -47,13 +47,13 @@ export type PrismicImageProps = {
} & (
| {
/**
* Widths used to build a `srcset` value for the Image field.
* Widths used to build a `srcset` value for the image field.
*
* If a `widths` prop is not given or `"defaults"` is passed, the
* following widths will be used: 640, 750, 828, 1080, 1200, 1920, 2048,
* 3840.
*
* If the Image field contains responsive views, each responsive view can
* If the image field contains responsive views, each responsive view can
* be used as a width in the resulting `srcset` by passing `"thumbnails"`
* as the `widths` prop.
*/
Expand All @@ -72,7 +72,7 @@ export type PrismicImageProps = {
*/
widths?: never
/**
* Pixel densities used to build a `srcset` value for the Image field.
* Pixel densities used to build a `srcset` value for the image field.
*
* If a `pixelDensities` prop is passed `"defaults"`, the following pixel
* densities will be used: 1, 2, 3.
Expand Down
2 changes: 1 addition & 1 deletion src/PrismicRichText/getRichTextComponentProps.ts
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ type DefineComponentRichTextComponentProps<
*
* ```typescript
* // Defining a new rich text component for a specific node type
* import { getSliceComponentProps } from "@prismicio/vue"
* import { getRichTextComponentProps } from "@prismicio/vue"
*
* defineProps(getRichTextComponentProps("heading1"))
* ```
Expand Down
4 changes: 2 additions & 2 deletions src/PrismicRichText/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,9 +7,9 @@ import type {

/**
* A map of Rich Text block types to Vue Components. It is used to render Rich
* Text or Title fields.
* Text or title fields.
*
* @see Templating Rich Text and Title fields from Prismic {@link https://prismic.io/docs/rich-text}
* @see Templating Rich Text and title fields from Prismic {@link https://prismic.io/docs/rich-text}
*/
export type VueRichTextSerializer = Partial<
Record<keyof typeof RichTextNodeType, VueRichTextComponent>
Expand Down
4 changes: 2 additions & 2 deletions src/PrismicText.vue
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ import type { ComponentOrTagName } from "./types"
*/
export type PrismicTextProps = {
/**
* The Prismic Rich Text field to render.
* The Prismic rich text field to render.
*/
field: RichTextField | null | undefined
Expand Down Expand Up @@ -47,7 +47,7 @@ if (DEV) {
watchEffect(() => {
if (typeof props.field === "string") {
throw new Error(
`[PrismicText] The "field" prop only accepts a Rich Text or Title field's value but was provided a different type of field instead (e.g. a Key Text or Select field). You can resolve this error by rendering the field value inline without <PrismicText>. For more details, see ${devMsg(
`[PrismicText] The "field" prop only accepts a Rich Text or title field's value but was provided a different type of field instead (e.g. a Key Text or Select field). You can resolve this error by rendering the field value inline without <PrismicText>. For more details, see ${devMsg(
"prismictext-works-only-with-rich-text-and-title-fields",
)}`,
)
Expand Down
10 changes: 5 additions & 5 deletions src/types.ts
Original file line number Diff line number Diff line change
Expand Up @@ -97,9 +97,9 @@ type PrismicPluginComponentsOptions = {

/**
* An optional map of Rich Text block types to Vue Components. It is used to
* render Rich Text or Title fields.
* render Rich Text or title fields.
*
* @see Templating Rich Text and Title fields from Prismic {@link https://prismic.io/docs/rich-text}
* @see Templating Rich Text and title fields from Prismic {@link https://prismic.io/docs/rich-text}
*/
richTextComponents?: VueRichTextSerializer

Expand Down Expand Up @@ -356,21 +356,21 @@ export type PrismicPluginHelpers = {
asDate: typeof asDate

/**
* Returns the URL of an Image field with optional image transformations (via
* Returns the URL of an image field with optional image transformations (via
* Imgix URL parameters). This is `@prismicio/client` {@link asImageSrc}
* function.
*/
asImageSrc: typeof asImageSrc

/**
* Creates a width-based `srcset` from an Image field with optional image
* Creates a width-based `srcset` from an image field with optional image
* transformations (via Imgix URL parameters). This is `@prismicio/client`
* {@link asImageWidthSrcSet} function.
*/
asImageWidthSrcSet: typeof asImageWidthSrcSet

/**
* Creates a pixel-density-based `srcset` from an Image field with optional
* Creates a pixel-density-based `srcset` from an image field with optional
* image transformations (via Imgix URL parameters). This is
* `@prismicio/client` {@link asImagePixelDensitySrcSet} function.
*/
Expand Down
2 changes: 1 addition & 1 deletion test/components-PrismicText.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -133,7 +133,7 @@ it("throws error if passed a string-based field (e.g. Key Text or Select)", () =
mount(PrismicText, {
props: {
// @ts-expect-error - We are purposely not providing a correct field.
field: "not a Rich Text field",
field: "not a rich text field",
wrapper: markRaw(WrapperComponent),
},
}),
Expand Down

0 comments on commit 55ee4c7

Please sign in to comment.