Description: A JET Input Date Mask allows a user to individually edit, step, or spin the\nvalues of the month, day, and year fields of a calendar date.
\nFor components that support validators, any invalid values entered by the user are not pushed into the value\nif validation fails: the valid property will change but the original value will remain unchanged.\nThe same thing applies to required validation: if required is set to true and the user clears the field,\nvalid will change, but empty values will not be pushed so the original value remains unchanged.\n
\nAn editable component runs validation (normal or deferred) based on the action performed on it\n(either by end-user or page author), and the state it was in when the action occurred. Examples\nof actions are - creating a component, user changing the value of the component by interacting\nwith it, the app setting a value programmatically, the app calling the validate() method etc. At\nthe time the action occurs, the component could already be showing errors, or can have a deferred\nerror or have no errors.\n
\n
\nThese factors also determine whether validation errors/messages get shown to the user immediately\nor get deferred. The following sections highlight the kinds of validation that are run and how\nmessages get handled.\n
\n\n
\n Normal Validation\n \n
\nNormal validation is run in the following cases on the display value, using the converter and\nvalidators (this includes async-validators) set on the component (for components that support these properties),\n\nand validation errors are reported to user immediately.\n
\n
When value changes as a result of user interaction all messages are cleared, including custom\nmessages added by the app, and full validation is run on the UI value. The steps performed are\noutlined below.\n\n
All messages are cleared and messagesCustom property is cleared
\n
If no converter is present then processing continues to next step. If a converter is\npresent, the UI value is first converted (i.e., parsed). If there is a parse error then\nthe messages are shown and processing returns.
\n
If there are no validators setup for the component then the value is set on the component.\nOtherwise all validators are run in sequence using the parsed value from the previous step. The\nimplicit required validator is run first if the component is marked required. When a validation error is\nencountered it is remembered and the next validator in the sequence is run.\n
NOTE: The value is trimmed before required validation is run
\n
\n
At the end of the validation run if there are errors, the messages are shown\nand processing returns. If there are async-validators, those errors are shown as soon as they\ncome in, and not until all validators, sync and async validators, are complete, does processing\nreturn, that is, value and valid are updated. If there are no errors, then the\nvalue property is updated and the formatted value displayed on the\nUI.
\n\n
\n
When the validate method is called by app, all messages are\ncleared and full validation is run using the display value. See validate\nmethod on the sub-classes for details. Note: JET validation is designed to catch user input errors, and not invalid\ndata passed from the server; this should be caught on the server.
\n
When certain properties change through programmatic intervention by app, the component\ndetermines whether it needs to run normal validation based on the state the component is in.\nRefer to the Mixed Validation section below for details.
\n
\n\n
\n Deferred Validation\n \n
\nDeferred validation is run in the following cases on the component value using the implicit\nrequired validator if required is true, and validation errors are deferred, i.e., not shown to user immediately.\nRefer to the Showing Deferred Messages section to\nunderstand how deferred messages can be shown.\n
\n
When a component is created and it is required deferred validation is run and no messages are cleared\n prior to running validation.\n Refer to the Validators\n Participating in Deferred Validation section for details.
\n
When the value property changes due to programmatic\n intervention deferred validation is run, after all messages and messagesCustom property are cleared.
\n
When the reset method is called, deferred validation is run\n after all messages and messagesCustom property are cleared.
\n
When certain properties change through programmatic intervention by app, the component\n determines whether it needs to run deferred validation based on the state the component is in.\n Refer to the Mixed Validation section below for details.
\n
\n\n
\n Mixed Validation\n \n
\nEither deferred or normal validation is run in the following cases based on the state the\ncomponent is in and any validation errors encountered are either hidden or shown to user.\n
\n
when disabled property changes. See disabled property for details.
\n
when converter property (if available) changes.
\n
when required property changes. See required property for details.
\n
when validators property changes (for components that support validators). See validators property for details.
\n
\n\n
\n Showing Deferred Messages\n \n
\nDeferred validation messages are displayed only when page author requests for it explicitly in\none of the following ways:\n
\n Validators Participating in Deferred Validation\n \n
\nThe required validator is the only validator type that participates in deferred validation.\nThe required property needs to be set to true for the required validator to run.\n\n
\n User Assistance Text\n \n
\n
\nUser assistive text provides guidance to help the user understand what data to enter or select.\n
\n
\nBy default all user assistance text shows inline.\nFor input components, it shows when the field takes focus. In other components\nit shows all the time. See the user-assistance-density property for other ways\nthe user assistance text can render, like in 'compact' mode, it will render as an icon on the label\nwhich when clicked will show the user assistance text in a notewindow.\n
\n
\nThe JET form component properties that are used for user assistance text are help.instruction,\nvalidator and converter hints (for components that support these properties), and help-hints.\nIn the Redwood theme for clarity only one user assistance text shows to the user.\nThe precedence rules are:\n
\n
help.instruction shows;
\n
if no help.instruction, then validator hint shows;
\n
if no help.instruction or validator hint, then help-hints.definition shows;
\n
if no help.instruction, validator hint, or help-hints.definition, then converter hint shows.
\n
help-hints.source always shows along side the above.
\n
\n\n
For components that support validators or converters, sometimes a hint shows that you do not want to show. To not show it,\n set the display-options.validator-hint and/or display-options.converter-hint property to 'none'.\n
\n
required property can be used to guide the user.\nIn Redwood, a required field shows the word Required under the field\nwhen the field is empty and does not have focus.\nThe mask placeholder is shown when the field is empty and has focus. The mask placeholder is not configurable.\n
\n\n
\n Touch End User Information\n \n
\n\n
\n \n
\n
Target
\n
Gesture
\n
Action
\n
\n \n \n
\n
Field (Not a Segment)
\n
Tap
\n
Sets focus to first segment. Show user assistance text.
\n
\n
\n
Segment
\n
Tap
\n
Sets focus to segment. Show user assistance text.
\n
\n
\n
Segment
\n
Double Tap
\n
If the date is complete, selects the entire date. Hitting backspace clears it.
\n
\n \n
\n\n
\n Keyboard End User Information\n \n
\n\n
\n \n
\n
Target
\n
Key
\n
Action
\n
\n \n \n
\n
Field
\n
Tab In
\n
Sets focus to first segment. Show user assistance text.
\n
\n
\n
Field
\n
Ctrl + A or Command + A
\n
If the date is complete, selects the entire date. Double clicking on the field also selects the date.
\n
\n
\n
Field with date selected
\n
Backspace/Delete
\n
Backspace or delete key clears the date. The mask placeholders will be shown again and focus will be on the first segment.
\n
\n
\n
Date Segment
\n
Backspace/Delete
\n
Clears the date segment. Focus remains on the date segment.
\n
\n
\n
Date Segment
\n
RightArrow
\n
Moves focus to the segment on the right. If focus is on the rightmost segment, the focus does not move.
\n
\n
\n
Date Segment
\n
LeftArrow
\n
Moves focus to the segment on the left. If focus is on the leftmost segment, the focus does not move.
\n
\n
\n
Date Segment
\n
UpArrow/DownArrow
\n
Increments or decrements the number by one in the segment. If there is no number in the segment, it initializes it to the current date.
\n
\n
\n
Date Segment
\n
End
\n
Increments the segment to the maximum number for the segment. For example, if on the month segment, this will set the number to 12. If on the year segment, this will set the number to 2100.
\n
\n
\n
Date Segment
\n
Home
\n
Decrements the segment to the minimum number for the segment. For example, if on the month segment, this will set the number to 1. If on the year segment, this will set the number to 1900.
\n
\n
\n
Date Segment
\n
Page Up/Page Down
\n
Increments or decrements the number by two in the month segment, by seven in the day segment, or by five in the year segment. If there is no number in the segment, it initializes it to the current date.
\n
\n \n
\n\n
\n Accessibility\n \n
\n\n
\nFor accessibility, set the label-hint property.\nIf there is no visible label, then to make this accessible to screen reader users,\nset the label-hint and label-edge='none'\nwhich renders an aria-label with the label-hint text.\n
\n\n
\nDisabled content: JET supports an accessible luminosity contrast ratio,\nas specified in WCAG 2.0 - Section 1.4.3 \"Contrast\",\nin the themes that are accessible. (See the \"Theming\" chapter of the JET Developer Guide for more information on which\nthemes are accessible.) Note that Section 1.4.3 says that text or images of text that are part of an inactive user\ninterface component have no contrast requirement. Because disabled content may not meet the minimum contrast ratio\nrequired of enabled content, it cannot be used to convey meaningful information.\n
",
"scope": "static",
"tagWithoutBrackets": "oj-c-input-date-mask",
"tagWithBrackets": "",
"domInterface": "CInputDateMaskElement",
"ojPageTitle": "<oj-c-input-date-mask>",
"camelCaseName": "InputDateMask",
"ojPageTitlePrefix": "Element: ",
"ojtsvcomponent": true,
"tstype": {
"target": "Type",
"value": "interface CInputDateMaskElement extends JetElement"
},
"ojsignature": [
{
"target": "Type",
"value": "interface CInputDateMaskElement extends JetElement"
}
],
"tsdeprecated": [
{
"type": "production",
"since": "17.0.0"
}
],
"extension": {
"catalog": {
"category": "Forms"
},
"vbdt": {
"module": "oj-c/input-date-mask",
"defaultColumns": 6,
"minColumns": 2
},
"oracle": {
"icon": "oj-ux-ico-masked-text-input",
"uxSpecs": [
"input-date-mask"
]
}
},
"ojmodule": "input-date-mask"
},
{
"id": "oj-c.InputDateMask#columnSpan",
"name": "columnSpan",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#columnSpan",
"scope": "instance",
"type": {
"names": [
"number"
]
},
"optional": true,
"ojdisplayname": "Column Span",
"ojshortdesc": "Specifies how many columns this component should span.",
"description": "Specifies how many columns this component should span.\nThis only takes effect when this component is a child of a form layout\nthat has direction 'row'.",
"defaultvalue": 1
},
{
"id": "oj-c.InputDateMask#containerReadonly",
"name": "containerReadonly",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#containerReadonly",
"scope": "instance",
"type": {
"names": [
"boolean"
]
},
"optional": true,
"ojdisplayname": "Container Readonly",
"ojshortdesc": "Specifies whether an ancestor container, like oj-c-form-layout, is readonly.",
"description": "Specifies whether an ancestor container, like oj-c-form-layout, is readonly.\nThis affects whether a readonly component renders in full or mixed readonly mode."
},
{
"id": "oj-c.InputDateMask#dateRangeOverflowMessageDetail",
"name": "dateRangeOverflowMessageDetail",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#dateRangeOverflowMessageDetail",
"scope": "instance",
"type": {
"names": [
"string"
]
},
"optional": true,
"ojdisplayname": "Date Range Overflow Message Detail",
"ojshortdesc": "Overrides the default validator's rangeOverflow message detail.",
"description": "
\nThe component-specific message detail when the date range validation fails when user's input date is greater than the max.\nIf the component needs a date range validation error message for overflow that is different from the default,\nset this property. It should be a translated string.\n
\nTokens: \n{value} - value entered by the user \n{max} - the maximum allowed value
\nUsage: \nThe date must be less than or equal to {max}."
},
{
"id": "oj-c.InputDateMask#dateRangeUnderflowMessageDetail",
"name": "dateRangeUnderflowMessageDetail",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#dateRangeUnderflowMessageDetail",
"scope": "instance",
"type": {
"names": [
"string"
]
},
"optional": true,
"ojdisplayname": "Date Range Underflow Message Detail",
"ojshortdesc": "Overrides the default validator's rangeUnderflow message detail.",
"description": "
\nThe component-specific message detail when the date range validation fails when the user's input date is less than the min.\nIf the component needs a date range validation error message for underflow that is different from the default,\nset this property. It should be a translated string.\n
\nTokens: \n{value} - value entered by the user \n{min} - the minimum allowed value
\nUsage: \nThe date must be greater than or equal to {min}."
},
{
"id": "oj-c.InputDateMask#disabled",
"name": "disabled",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#disabled",
"scope": "instance",
"type": {
"names": [
"boolean"
]
},
"optional": true,
"ojdisplayname": "Disabled",
"ojshortdesc": "Specifies whether the component is disabled.",
"description": "Whether the component is disabled. The default is false.\n\n
\nWhen the disabled property changes due to programmatic\nintervention, the component may clear messages and run validation in some cases. \n
\n
when a required component is initialized as disabled\nvalue=\"{{currentValue}}\" required disabled,\ndeferred validation is skipped.
\n
when a disabled component is enabled,\n
\n
if component is invalid and showing messages then all component messages are cleared,\n and full validation run using the display value.\n
\n
if there are validation errors, they are shown.
\n
if no errors result from the validation, the value\n property is updated. Page authors can listen to the valueChanged\n event to clear custom errors.
\n
\n
\n\n
if component is valid and has no errors then deferred validation is run.\n
\n
if there is a deferred validation error, then the valid property is updated.
\n
\n
\n
if component is invalid and deferred errors then component messages are cleared and\n deferred validation re-run.\n
\n
if there is a deferred validation error, then the valid property is updated.
\n
\n
\n
\n
\n
when enabled component is disabled then no validation is run and the component appears\ndisabled.
\n
\n",
"defaultvalue": false
},
{
"id": "oj-c.InputDateMask#displayOptions",
"name": "displayOptions",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#displayOptions",
"scope": "instance",
"type": {
"names": [
"object"
]
},
"optional": true,
"ojdisplayname": "Display Options",
"description": "Display options for auxiliary content that determines whether or not it should be displayed.",
"tstype": [
{
"target": "Type",
"value": "oj-c.InputDateMask.DisplayOptionsProps",
"jsdocOverride": true
}
]
},
{
"id": "oj-c.InputDateMask#help",
"name": "help",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#help",
"scope": "instance",
"type": {
"names": [
"object"
]
},
"optional": true,
"ojdisplayname": "Help",
"description": "Form component help information.",
"tstype": [
{
"target": "Type",
"value": "oj-c.InputDateMask.Help",
"jsdocOverride": true
}
]
},
{
"id": "oj-c.InputDateMask#helpHints",
"name": "helpHints",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#helpHints",
"scope": "instance",
"type": {
"names": [
"object"
]
},
"optional": true,
"ojdisplayname": "Help Hints",
"description": "The helpHints object contains a definition property and a source property.",
"tstype": [
{
"target": "Type",
"value": "oj-c.InputDateMask.HelpHints",
"jsdocOverride": true
}
]
},
{
"id": "oj-c.InputDateMask#labelEdge",
"name": "labelEdge",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#labelEdge",
"scope": "instance",
"type": {
"names": [
"\"none\"",
"\"start\"",
"\"top\"",
"\"inside\""
]
},
"optional": true,
"ojdisplayname": "Label Edge",
"ojshortdesc": "Specifies how the label is positioned for the component",
"description": "Specifies how the label of the component is positioned when the label-hint\nattribute is set on the component.",
"ojvalues": [
{
"name": "inside",
"description": "The label floats over the input element, but moves up on focus or when the component has a value (default, if unspecified).",
"displayName": "Inside",
"type": {
"names": [
"string"
]
}
},
{
"name": "none",
"description": "The component will not create a label, but instead set the aria-label property on the input element.",
"displayName": "None",
"type": {
"names": [
"string"
]
}
},
{
"name": "start",
"description": "The label will be placed before the start of the component.",
"displayName": "Start",
"type": {
"names": [
"string"
]
}
},
{
"name": "top",
"description": "The label will be placed on top of the component.",
"displayName": "Top",
"type": {
"names": [
"string"
]
}
}
],
"ojvalueskeeporder": true
},
{
"id": "oj-c.InputDateMask#labelHint",
"name": "labelHint",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#labelHint",
"scope": "instance",
"type": {
"names": [
"string"
]
},
"optional": false,
"ojdisplayname": "Label Hint",
"ojshortdesc": "Represents a hint for rendering a label on the component.",
"description": "Represents a hint for rendering a label on the component.\nThis is used in combination with the label-edge attribute to control how the label should be rendered."
},
{
"id": "oj-c.InputDateMask#labelStartWidth",
"name": "labelStartWidth",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#labelStartWidth",
"scope": "instance",
"type": {
"names": [
"number|string"
]
},
"optional": true,
"ojdisplayname": "Label Start Width",
"ojshortdesc": "The width of the label when labelEdge is 'start'.",
"description": "
The width of the label when labelEdge is 'start'.
\n
This attribute accepts values of type\n0 | `--${string}` | `${number}%` | `${number}x` | `calc(${string})`
"
},
{
"id": "oj-c.InputDateMask#labelWrapping",
"name": "labelWrapping",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#labelWrapping",
"scope": "instance",
"type": {
"names": [
"\"truncate\"",
"\"wrap\""
]
},
"optional": true,
"ojdisplayname": "Label Wrapping",
"ojshortdesc": "Should the labels wrap or truncate when there is not enough available space.",
"description": "Should the labels wrap or truncate when there is not enough available space.",
"tsdeprecated": [
{
"type": "deprecated",
"since": "18.0.0",
"description": "Label truncation for 'start' and 'top' aligned labels is no longer recommended by the Redwood Design System. The default for labelWrapping was 'wrap' and that is now the only suggested pattern by UX design for 'start' and 'top' aligned labels. 'inside' aligned labels are always truncated per UX design and are not affected by this property's value."
}
],
"ojvalues": [
{
"name": "truncate",
"description": "Label will truncate if needed.",
"displayName": "Truncate",
"type": {
"names": [
"string"
]
}
},
{
"name": "wrap",
"description": "Label will wrap if needed.",
"displayName": "Wrap",
"type": {
"names": [
"string"
]
}
}
],
"ojvalueskeeporder": true
},
{
"id": "oj-c.InputDateMask#max",
"name": "max",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#max",
"scope": "instance",
"type": {
"names": [
"string|null"
]
},
"optional": true,
"ojdisplayname": "Max",
"ojshortdesc": "The maximum selectable date, in ISO string format",
"description": "The maximum selectable date, in date only ISO string format.\nThe date the user enters must be less than or equal to the max date, otherwise the user will see an error.\nThis must be a date only ISO string with no time, otherwise an error is thrown and the component will not render.\nWhen set to null, there is no maximum."
},
{
"id": "oj-c.InputDateMask#maxWidth",
"name": "maxWidth",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#maxWidth",
"scope": "instance",
"type": {
"names": [
"number|string"
]
},
"optional": true,
"ojdisplayname": "Max Width",
"ojshortdesc": "The max width of the control.",
"description": "Specifies the component's max width. If unset, the default max width is 100%.",
"ojvalues": [
{
"name": "sm",
"type": {
"names": [
"string"
]
}
},
{
"name": "md",
"type": {
"names": [
"string"
]
}
}
],
"ojvalueskeeporder": true,
"tstype": [
{
"target": "Type",
"value": "number|string|\"sm\"|\"md\"",
"jsdocOverride": true
}
]
},
{
"id": "oj-c.InputDateMask#messagesCustom",
"name": "messagesCustom",
"memberof": "oj-c.InputDateMask",
"meta": {
"filename": "input-date-mask.tsx",
"path": "web/components/oj-c/input-date-mask"
},
"kind": "member",
"longname": "oj-c.InputDateMask#messagesCustom",
"scope": "instance",
"type": {
"names": [
"Array