From 80f278adffefda1e2c0ac7383579b7c056958b98 Mon Sep 17 00:00:00 2001 From: Arun Date: Wed, 11 Nov 2015 17:11:27 -0500 Subject: [PATCH] Made UI optional; created attribute and API separation --- proposal.html | 80 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 55 insertions(+), 25 deletions(-) diff --git a/proposal.html b/proposal.html index b693549..d27dcbe 100644 --- a/proposal.html +++ b/proposal.html @@ -109,6 +109,7 @@

Returning Files and Directories

When this specification says to return a file or directory sequence promise on a given present working directory, the user agent should run the following steps:

    +

  1. If the result of running is settings object a secure context with the incumbent settings object is Not Secure, return a new promise rejected with a "SecurityError" exception.

  2. Let p be a new promise and s a sequence, initially set to an empty sequence.

  3. Run the following steps asynchronously:

      @@ -124,6 +125,53 @@

      Returning Files and Directories

    1. Return p.

    A common method on both the HTMLInputElement and on the Directory interface called getFilesAndDirectories() returns files and subdirectories for a given directory using the steps above. Each method invoking the steps above must specify what to consider as the present working directory.

    + +
    +

    Triggering a Directory Picker

    +

    When an input element's type attribute is in the File Upload state, the rules in this section apply [[!HTML]].

    +

    User agents may surface a directory picker, which may also serve as a file picker; this is an unspecified piece of user interface that a user agent may deploy, and may expand upon any existing user interface already in place for selecting files when the input element's type attribute is in the File Upload state. This generally happens synchronously and is considered a blocking operation. When this specification says to trigger a directory picker a user agent must follow the steps below (and may optionally follow the steps labeled "may" [[!RFC2119]]):

    +
      +

    1. If the result of running is settings object a secure context with the incumbent settings object is Not Secure, the user agent must throw a SecurityError exception and additionally may prevent a directory picker from being shown at all.

      2. +

    2. If the user agent is capable of surfacing both a directory picker and a file picker in a single user interface element, this user agent is said to have a Single File and Directory Picker. This user agent must expose a value of true on the isFilesAndDirectoriesSupported attribute of the HTMLInputElement.

      +

      User agents in practice may reuse user interface elements from the host OS. If the host OS supports a Single File and Directory Picker a file input with a single button that enables the combined picker may be rendered and may resemble the suggested user interface element below:

      +
      +
      + 1 file selected. +
      Choose file(s)...
      +
      +
      Clicking "Choose file(s)" activates combined file & directory picker.
      +
      +

      Currently, only OSX exposes a unified picker.

      + +
      3. +

    3. If the user agent does not have a Single File and Directory Picker it is said to have Distinct File and Directory Pickers. This user agent must expose a value of false on the isFilesAndDirectoriesSupported attribute of the HTMLInputElement.

      +

      If the user agent has Distinct File and Directory Pickers, possibly reusing user interface elements from the host OS, a file input that enables two separate pickers (file and directory) via two different buttons may be rendered and may resemble the suggested user interface element below:

      +
      +
      +
      Choose files...
      +
      Choose directories...
      +
      +
      Default (no selection)
      +
      +
      +
      + 2 files selected. +
      ×
      +
      +
      After a selection has been made; clearing the field may reset it to .
      +
      +
      4. +

    4. If the user agent has Distinct File and Directory Pickers and is set to trigger in Directory Picker Only mode, it may only surface a picker that allows for directory picking, or it may surface a picker featuring two separate buttons as in figure two above. The suggested user interface element below may be used to surface an option to only pick directories:

      +
      +
      +
      Choose directories...
      +
      +
      Clicking "Choose directories..." activates a directory picker only.
      +
      + +
      5. +
    +
    @@ -197,33 +245,13 @@

    File Input

    <!-- Adding the multiple attribute is useful because older browsers would be able --> <!-- to accept multiple files even if they do not recognize the directory attribute --> -

    If the host OS supports a combined file and directory picker (i.e. HTMLInputElement.isFilesAndDirectoriesSupported === true) a file input with a single button that enables the combined picker MUST be rendered:

    -
    -
    - 1 file selected. -
    Choose file(s)...
    -
    -
    Clicking "Choose file(s)" activates combined file & directory picker
    -
    -

    If it is not supported (i.e. HTMLInputElement.isFilesAndDirectoriesSupported === false) a file input that enables two separate pickers (file and directory) via two different buttons MUST be rendered:

    -
    -
    -
    Choose files...
    -
    Choose directory...
    -
    -
    Default (no selection)
    -
    -
    -
    - 2 files selected. -
    ×
    -
    -
    After a selection has been made; clearing the field will reset it to
    -
    + + +

    The default click behavior of such a file input MUST trigger the file picker. Calling HTMLInputElement.chooseDirectory on the file input element MUST trigger the directory picker.

    HTMLInputElement.isFilesAndDirectoriesSupported -

    On getting, this attribute is true if the host OS supports a single dialog capable of picking both files and directories simultaneously, false otherwise.

    +

    On getting, this attribute must be true if the user agent will expose a Single File and Directory Picker, and false if the user agent will expose Distinct File and Directory Pickers.

    HTMLInputElement.getFilesAndDirectories

    When the getFilesAndDirectories() method is called, the user agent must run the steps below:

    @@ -257,7 +285,9 @@

    File Input

    HTMLInputElement.chooseDirectory -

    Triggers the directory picker if HTMLInputElement.isFilesAndDirectoriesSupported === false, otherwise triggers the default click behavior of the input element.

    +

    When the choseDirectory() method is called, a user agent must trigger a directory picker in Directory Picker Only mode.

    + +

    Form Submission