Skip to content

Commit

Permalink
feat: improve description fields with progressive disclosure
Browse files Browse the repository at this point in the history
  • Loading branch information
@andybywire
andybywire committed Jun 12, 2023
2 parents 4efbaea + 7fa7f03 commit edb7284
Show file tree
Hide file tree
Showing 3 changed files with 164 additions and 42 deletions.
18 changes: 9 additions & 9 deletions src/modules/baseIriField.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
*/

import {defineField} from 'sanity'
import {DescriptionDetail} from '../styles'
import {StyledDescription} from '../styles'
import {RdfUri} from '../components/inputs'

export default [
Expand All @@ -15,24 +15,24 @@ export default [
validation: (Rule) =>
Rule.required().error(`Please supply a base URI in the format 'http://example.com/'`),
description: (
<details>
<StyledDescription>
<summary>
The root URI (Uniform Resource Identifier) used to create unique concept identifiers.
</summary>
<DescriptionDetail>
<div>
Unique identifiers allow for the clear an unambiguous identification of concepts across
namespaces, for example between <code>https://shipparts.com/vocab#Bow</code> and {}
<code>https://wrappingsupplies.com/vocab#Bow</code>.
</DescriptionDetail>
<DescriptionDetail>
</div>
<div>
In most cases, it makes sense for your base URI to be the root or a subdirectory of your
website. In all cases, the URI you choose should be in a domain that you control.
</DescriptionDetail>
<DescriptionDetail>
</div>
<div>
For new Concepts and Concept Schemes, the Base URI field is pre-populated based on the
most recently used Base URI value.
</DescriptionDetail>
</details>
</div>
</StyledDescription>
),
options: {
collapsible: true,
Expand Down
174 changes: 144 additions & 30 deletions src/skosConcept.tsx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@
// import config from 'config:taxonomy-manager'
import {AiFillTag, AiFillTags} from 'react-icons/ai'
import {defineType, defineField} from 'sanity'
import {DescriptionDetail} from './styles'
import {WarningOutlineIcon} from '@sanity/icons'
import {StyledDescription} from './styles'
import baseIriField from './modules/baseIriField'
import {Identifier} from './components/inputs'
import {randomKey} from '@sanity/util/content'
Expand Down Expand Up @@ -48,9 +49,7 @@ export default function skosConcept(baseUri?: string) {
name: 'prefLabel',
title: 'Preferred Label',
type: 'string',
description:
'The preferred lexical label for this concept. This label is also used to unambiguously represent this concept via the concept IRI.',
// If there is a published concept with the current document's prefLabel, return an error message, but only for concepts with distinct _ids — otherwise editing an existing concept shows the error message as well.
description: 'The preferred lexical label for this concept.',
validation: (Rule) =>
Rule.required().custom((prefLabel, context) => {
const {getClient} = context
Expand All @@ -71,39 +70,136 @@ export default function skosConcept(baseUri?: string) {
name: 'definition',
title: 'Definition',
type: 'text',
description: 'A complete explanation of the intended meaning of the concept',
description: (
<StyledDescription>
<summary>A complete explanation of the intended meaning of the concept.</summary>
<div>
<kbd>
Example: documentation
<br />
Definition: "The process of storing and retrieving information in all fields of
knowledge."
</kbd>
<p>
For more information on the recommended usage of the SKOS documentation properties,
see
<a
href="https://www.w3.org/TR/2009/NOTE-skos-primer-20090818/#secdocumentation"
target="_blank"
rel="noreferrer"
>
{' '}
W3C SKOS Primer: 2.4 Documentary Notes
</a>
</p>
</div>
</StyledDescription>
),
rows: 3,
}),
defineField({
name: 'example',
title: 'Examples',
type: 'text',
description: 'An example of the use of the concept.',
description: (
<StyledDescription>
<summary>An example of the use of the concept.</summary>
<div>
<kbd>
Example: organizations of science and culture
<br />
Example: "academies of science, general museums, world fairs"
</kbd>
<p>
For more information on the recommended usage of the SKOS documentation properties,
see
<a
href="https://www.w3.org/TR/2009/NOTE-skos-primer-20090818/#secdocumentation"
target="_blank"
rel="noreferrer"
>
{' '}
W3C SKOS Primer: 2.4 Documentary Notes
</a>
</p>
</div>
</StyledDescription>
),
rows: 3,
}),
defineField({
name: 'scopeNote',
title: 'Scope Note',
type: 'text',
description:
'A brief statement on the intended meaning of this concept, especially as an indication of how the use of the concept is limited in indexing practice',
description: (
<StyledDescription>
<summary>
A brief statement on the intended meaning of this concept, especially as an indication
of how the use of the concept is limited in indexing practice.
</summary>
<div>
<kbd>
Example: microwave frequencies
<br />
Scope Note: "Used for frequencies between 1Ghz and 300Ghz"
</kbd>
<p>
For more information on the recommended usage of the SKOS documentation properties,
see
<a
href="https://www.w3.org/TR/2009/NOTE-skos-primer-20090818/#secdocumentation"
target="_blank"
rel="noreferrer"
>
{' '}
W3C SKOS Primer: 2.4 Documentary Notes
</a>
</p>
</div>
</StyledDescription>
),
rows: 3,
}),
defineField({
name: 'altLabel',
title: 'Alternate Label(s)',
type: 'array',
description:
'Alternative labels can be used to assign synonyms, near-synonyms, abbreviations, and acronyms to a concept. Preferred, alternative, and hidden label sets must not overlap.',
description: (
<StyledDescription>
<summary>Synonyms, near-synonyms, abbreviations, and acronyms to a concept.</summary>
<div>
<p>
<WarningOutlineIcon /> Preferred, alternative, and hidden label sets must not
overlap.
</p>
</div>
</StyledDescription>
),
of: [{type: 'string'}],
validation: (Rule) => Rule.unique(),
}),
defineField({
name: 'hiddenLabel',
title: 'Hidden Label(s)',
type: 'array',
description:
'Hidden labels are for character strings that need to be accessible to applications performing text-based indexing and search operations, but not visible otherwise. Hidden labels may for instance be used to include misspelled variants of other lexical labels. Preferred, alternative, and hidden label sets must not overlap.',
description: (
<StyledDescription>
<summary>
Character strings that need to be accessible to applications performing text-based
indexing and search operations, but which should not be displayed to end users.
</summary>
<div>
<p>
Hidden labels may for instance be used to include misspelled variants of other
lexical labels.
</p>
<p>
<WarningOutlineIcon /> Preferred, alternative, and hidden label sets must not
overlap.
</p>
</div>
</StyledDescription>
),
of: [{type: 'string'}],
validation: (Rule) => Rule.unique(),
}),
Expand All @@ -129,8 +225,17 @@ export default function skosConcept(baseUri?: string) {
defineField({
name: 'broader',
title: 'Broader Concept(s)',
description:
'Broader relationships create a hierarchy between concepts, for example to create category/subcategory, part/whole, or class/instance relationships.',
description: (
<StyledDescription>
<summary>
Create hierarchy between concepts, for example to create category/subcategory,
part/whole, or class/instance relationships.
</summary>
<div>
<p>Broader and Associated relationships are mutually exclusive.</p>
</div>
</StyledDescription>
),
type: 'array',
of: [
{
Expand All @@ -157,8 +262,17 @@ export default function skosConcept(baseUri?: string) {
defineField({
name: 'related',
title: 'Related Concept(s)',
description:
'Associative links between concepts indicate that the two are inherently "related", but that one is not in any way more general than the other. Broader and Associated relationships are mutually exclusive.',
description: (
<StyledDescription>
<summary>
Indicate that two concepts are inherently "related", but that one is not in any way
more general than the other.
</summary>
<div>
<p>Broader and Associated relationships are mutually exclusive.</p>
</div>
</StyledDescription>
),
type: 'array',
of: [
{
Expand All @@ -172,13 +286,13 @@ export default function skosConcept(baseUri?: string) {
title: 'History Notes',
type: 'text',
description: (
<details>
<StyledDescription>
<summary>Significant changes to the meaning of the form of this concept.</summary>
<DescriptionDetail>
<div>
<kbd>
Example: childAbuse
Example: person with disabilities
<br />
History Note: "Estab. 1975; heading was: Cruelty to children [1952 - 1975]."
History Note: "Estab. 1992; heading was: handicapped [1884 - 1992]."
</kbd>
<p>
For more information on the recommended usage of the SKOS documentation properties,
Expand All @@ -192,8 +306,8 @@ export default function skosConcept(baseUri?: string) {
W3C SKOS Primer: 2.4 Documentary Notes
</a>
</p>
</DescriptionDetail>
</details>
</div>
</StyledDescription>
),
rows: 3,
}),
Expand All @@ -202,13 +316,13 @@ export default function skosConcept(baseUri?: string) {
title: 'Editorial Notes',
type: 'text',
description: (
<details>
<StyledDescription>
<summary>
Information to aid in administrative housekeeping, such as reminders of editorial work
still to be done, or warnings in the event that future editorial changes might be
made.
</summary>
<DescriptionDetail>
<div>
<kbd>
Example: doubleclick
<br />
Expand All @@ -226,8 +340,8 @@ export default function skosConcept(baseUri?: string) {
W3C SKOS Primer: 2.4 Documentary Notes
</a>
</p>
</DescriptionDetail>
</details>
</div>
</StyledDescription>
),
rows: 3,
}),
Expand All @@ -236,11 +350,11 @@ export default function skosConcept(baseUri?: string) {
title: 'Change Notes',
type: 'text',
description: (
<details>
<StyledDescription>
<summary>
Fine-grained changes to a concept, for the purposes of administration and maintenance.
</summary>
<DescriptionDetail>
<div>
<kbd>
Example: tomato
<br />
Expand All @@ -258,8 +372,8 @@ export default function skosConcept(baseUri?: string) {
W3C SKOS Primer: 2.4 Documentary Notes
</a>
</p>
</DescriptionDetail>
</details>
</div>
</StyledDescription>
),
rows: 3,
}),
Expand Down
14 changes: 11 additions & 3 deletions src/styles.ts
View file
Original file line number Diff line number Diff line change
@@ -1,9 +1,17 @@
import styled from 'styled-components'
import {hues} from '@sanity/color'

export const DescriptionDetail = styled.p`
margin-top: 0.5rem;
margin-left: 0.75rem;
export const StyledDescription = styled.details`
summary {
cursor: pointer;
}
div {
margin-top: 0.5rem;
margin-left: 0.75rem;
svg {
padding-right: 0.25rem;
}
}
`
export const InlineHelp = styled.div`
margin-top: 2rem;
Expand Down

0 comments on commit edb7284

Please sign in to comment.